From 62d8fa516e97e0686cb8e4ab31d6388cb05e26d0 Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Thu, 16 Apr 2026 15:54:55 +0200 Subject: [PATCH 01/20] Modernized dashboard --- .gitignore | 1 + .../session-2026-04-14T22-54-43-088Z.json | 15 + .../session-2026-04-14T22-54-44-115Z.json | 15 + .../session-2026-04-14T22-54-45-130Z.json | 15 + .../session-2026-04-14T22-54-46-149Z.json | 21 + .../session-2026-04-14T22-54-47-158Z.json | 15 + .../session-2026-04-14T22-54-48-220Z.json | 21 + .../session-2026-04-14T22-54-49-480Z.json | 21 + .../session-2026-04-14T22-54-50-630Z.json | 15 + .../session-2026-04-14T22-54-51-721Z.json | 15 + .../session-2026-04-14T22-55-05-056Z.json | 21 + .../session-2026-04-14T22-55-07-822Z.json | 21 + .../session-2026-04-14T22-55-08-837Z.json | 23 + .../session-2026-04-14T22-55-09-811Z.json | 21 + .../session-2026-04-14T23-03-43-971Z.json | 15 + .../session-2026-04-14T23-03-45-016Z.json | 15 + .../session-2026-04-14T23-03-46-067Z.json | 15 + .../session-2026-04-14T23-03-47-170Z.json | 21 + .../session-2026-04-14T23-03-48-203Z.json | 15 + .../session-2026-04-14T23-03-49-217Z.json | 21 + .../session-2026-04-14T23-03-50-369Z.json | 21 + .../session-2026-04-14T23-03-51-347Z.json | 15 + .../session-2026-04-14T23-03-52-320Z.json | 15 + .../session-2026-04-14T23-04-00-322Z.json | 15 + .../session-2026-04-14T23-04-01-371Z.json | 15 + .../session-2026-04-14T23-04-02-416Z.json | 15 + .../session-2026-04-14T23-04-03-444Z.json | 21 + .../session-2026-04-14T23-04-04-520Z.json | 15 + .../session-2026-04-14T23-04-05-606Z.json | 21 + .../session-2026-04-14T23-04-05-768Z.json | 21 + .../session-2026-04-14T23-04-06-683Z.json | 21 + .../session-2026-04-14T23-04-07-780Z.json | 15 + .../session-2026-04-14T23-04-08-872Z.json | 21 + .../session-2026-04-14T23-04-08-989Z.json | 15 + .../session-2026-04-14T23-04-09-934Z.json | 23 + .../session-2026-04-14T23-04-10-942Z.json | 21 + .../session-2026-04-14T23-04-22-645Z.json | 21 + .../session-2026-04-14T23-04-26-263Z.json | 21 + .../session-2026-04-14T23-04-27-404Z.json | 23 + .../session-2026-04-14T23-04-28-550Z.json | 21 + .../session-2026-04-14T23-10-25-183Z.json | 15 + .../session-2026-04-14T23-10-26-320Z.json | 15 + .../session-2026-04-14T23-10-27-465Z.json | 15 + .../session-2026-04-14T23-10-28-613Z.json | 21 + .../session-2026-04-14T23-10-29-736Z.json | 15 + .../session-2026-04-14T23-10-30-829Z.json | 21 + .../session-2026-04-14T23-10-31-828Z.json | 21 + .../session-2026-04-14T23-10-32-912Z.json | 15 + .../session-2026-04-14T23-10-34-024Z.json | 15 + .../session-2026-04-14T23-10-47-636Z.json | 21 + .../session-2026-04-14T23-10-51-061Z.json | 21 + .../session-2026-04-14T23-10-52-120Z.json | 23 + .../session-2026-04-14T23-10-53-238Z.json | 21 + .../session-2026-04-14T23-11-38-417Z.json | 15 + .../session-2026-04-14T23-11-39-411Z.json | 15 + .../session-2026-04-14T23-11-40-431Z.json | 15 + .../session-2026-04-14T23-11-41-446Z.json | 21 + .../session-2026-04-14T23-11-42-493Z.json | 15 + .../session-2026-04-14T23-11-43-551Z.json | 21 + .../session-2026-04-14T23-11-44-687Z.json | 21 + .../session-2026-04-14T23-11-45-707Z.json | 15 + .../session-2026-04-14T23-11-46-731Z.json | 15 + .../session-2026-04-14T23-12-00-105Z.json | 21 + .../session-2026-04-14T23-12-03-222Z.json | 21 + .../session-2026-04-14T23-12-04-283Z.json | 23 + .../session-2026-04-14T23-12-05-402Z.json | 21 + .../session-2026-04-14T23-14-51-982Z.json | 15 + .../session-2026-04-14T23-14-53-055Z.json | 15 + .../session-2026-04-14T23-14-54-170Z.json | 15 + .../session-2026-04-14T23-14-55-333Z.json | 21 + .../session-2026-04-14T23-14-56-491Z.json | 15 + .../session-2026-04-14T23-14-57-538Z.json | 21 + .../session-2026-04-14T23-14-58-686Z.json | 21 + .../session-2026-04-14T23-14-59-866Z.json | 15 + .../session-2026-04-14T23-15-01-163Z.json | 15 + .../session-2026-04-14T23-15-14-781Z.json | 21 + .../session-2026-04-14T23-15-17-805Z.json | 21 + .../session-2026-04-14T23-15-18-869Z.json | 23 + .../session-2026-04-14T23-15-19-906Z.json | 21 + .../session-2026-04-15T05-42-46-858Z.json | 15 + .../session-2026-04-15T05-42-47-837Z.json | 15 + .../session-2026-04-15T05-42-48-845Z.json | 15 + .../session-2026-04-15T05-42-49-912Z.json | 21 + .../session-2026-04-15T05-42-50-981Z.json | 15 + .../session-2026-04-15T05-42-52-057Z.json | 21 + .../session-2026-04-15T05-42-53-156Z.json | 21 + .../session-2026-04-15T05-42-54-152Z.json | 15 + .../session-2026-04-15T05-42-55-212Z.json | 15 + .../session-2026-04-15T05-43-08-582Z.json | 21 + .../session-2026-04-15T05-43-11-415Z.json | 21 + .../session-2026-04-15T05-43-12-444Z.json | 23 + .../session-2026-04-15T05-43-13-440Z.json | 21 + .../session-2026-04-15T06-08-04-176Z.json | 15 + .../session-2026-04-15T06-08-05-195Z.json | 15 + .../session-2026-04-15T06-08-06-217Z.json | 15 + .../session-2026-04-15T06-08-07-298Z.json | 21 + .../session-2026-04-15T06-08-08-331Z.json | 15 + .../session-2026-04-15T06-08-09-323Z.json | 21 + .../session-2026-04-15T06-08-10-303Z.json | 21 + .../session-2026-04-15T06-08-11-309Z.json | 15 + .../session-2026-04-15T06-08-12-311Z.json | 15 + .../session-2026-04-15T06-08-25-626Z.json | 21 + .../session-2026-04-15T06-08-28-421Z.json | 21 + .../session-2026-04-15T06-08-29-414Z.json | 23 + .../session-2026-04-15T06-08-30-388Z.json | 21 + .../session-2026-04-15T10-31-45-291Z.json | 15 + .../session-2026-04-15T10-31-46-462Z.json | 15 + .../session-2026-04-15T10-31-47-745Z.json | 15 + .../session-2026-04-15T10-31-48-923Z.json | 21 + .../session-2026-04-15T10-31-50-130Z.json | 15 + .../session-2026-04-15T10-31-51-230Z.json | 21 + .../session-2026-04-15T10-31-52-343Z.json | 21 + .../session-2026-04-15T10-31-53-393Z.json | 15 + .../session-2026-04-15T10-31-54-377Z.json | 15 + .../session-2026-04-15T10-32-07-614Z.json | 21 + .../session-2026-04-15T10-32-10-392Z.json | 21 + .../session-2026-04-15T10-32-11-378Z.json | 23 + .../session-2026-04-15T10-32-12-357Z.json | 21 + .../session-2026-04-15T10-48-48-787Z.json | 15 + .../session-2026-04-15T10-48-49-909Z.json | 15 + .../session-2026-04-15T10-48-51-093Z.json | 15 + .../session-2026-04-15T10-48-52-294Z.json | 21 + .../session-2026-04-15T10-48-53-820Z.json | 15 + .../session-2026-04-15T10-48-55-125Z.json | 26 + .../session-2026-04-15T10-48-56-313Z.json | 21 + .../session-2026-04-15T10-48-57-419Z.json | 15 + .../session-2026-04-15T10-48-58-476Z.json | 15 + .../session-2026-04-15T10-49-11-760Z.json | 21 + .../session-2026-04-15T10-49-14-489Z.json | 21 + .../session-2026-04-15T10-49-15-508Z.json | 23 + .../session-2026-04-15T10-49-16-519Z.json | 21 + .../session-2026-04-15T11-26-48-850Z.json | 15 + .../session-2026-04-15T11-26-49-859Z.json | 15 + .../session-2026-04-15T11-26-50-877Z.json | 15 + .../session-2026-04-15T11-26-51-908Z.json | 21 + .../session-2026-04-15T11-26-52-921Z.json | 15 + .../session-2026-04-15T11-26-53-965Z.json | 21 + .../session-2026-04-15T11-26-54-962Z.json | 21 + .../session-2026-04-15T11-26-55-943Z.json | 15 + .../session-2026-04-15T11-26-56-916Z.json | 15 + .../session-2026-04-15T11-27-10-127Z.json | 21 + .../session-2026-04-15T11-27-12-867Z.json | 21 + .../session-2026-04-15T11-27-13-914Z.json | 23 + .../session-2026-04-15T11-27-14-921Z.json | 21 + .../session-2026-04-15T11-37-32-784Z.json | 15 + .../session-2026-04-15T11-37-33-817Z.json | 15 + .../session-2026-04-15T11-37-34-847Z.json | 15 + .../session-2026-04-15T11-37-35-901Z.json | 21 + .../session-2026-04-15T11-37-36-913Z.json | 15 + .../session-2026-04-15T11-37-37-928Z.json | 21 + .../session-2026-04-15T11-37-38-957Z.json | 21 + .../session-2026-04-15T11-37-39-942Z.json | 15 + .../session-2026-04-15T11-37-40-939Z.json | 15 + .../session-2026-04-15T11-37-54-259Z.json | 21 + .../session-2026-04-15T11-37-57-203Z.json | 21 + .../session-2026-04-15T11-37-58-198Z.json | 23 + .../session-2026-04-15T11-37-59-194Z.json | 21 + .../session-2026-04-15T15-13-12-967Z.json | 15 + .../session-2026-04-15T15-13-13-976Z.json | 15 + .../session-2026-04-15T15-13-15-013Z.json | 15 + .../session-2026-04-15T15-13-16-008Z.json | 21 + .../session-2026-04-15T15-13-16-997Z.json | 15 + .../session-2026-04-15T15-13-18-026Z.json | 21 + .../session-2026-04-15T15-13-19-015Z.json | 21 + .../session-2026-04-15T15-13-20-017Z.json | 15 + .../session-2026-04-15T15-13-21-019Z.json | 15 + .../session-2026-04-15T15-13-34-343Z.json | 21 + .../session-2026-04-15T15-13-37-076Z.json | 21 + .../session-2026-04-15T15-13-38-124Z.json | 23 + .../session-2026-04-15T15-13-39-136Z.json | 21 + .../session-2026-04-15T15-21-59-954Z.json | 15 + .../session-2026-04-15T15-22-01-197Z.json | 15 + .../session-2026-04-15T15-22-02-257Z.json | 15 + .../session-2026-04-15T15-22-03-263Z.json | 21 + .../session-2026-04-15T15-22-04-243Z.json | 15 + .../session-2026-04-15T15-22-05-299Z.json | 21 + .../session-2026-04-15T15-22-06-321Z.json | 21 + .../session-2026-04-15T15-22-07-346Z.json | 15 + .../session-2026-04-15T15-22-08-376Z.json | 15 + .../session-2026-04-15T15-22-21-742Z.json | 21 + .../session-2026-04-15T15-22-24-663Z.json | 21 + .../session-2026-04-15T15-22-25-687Z.json | 23 + .../session-2026-04-15T15-22-26-773Z.json | 21 + .../session-2026-04-15T15-24-50-268Z.json | 15 + .../session-2026-04-15T15-24-51-309Z.json | 15 + .../session-2026-04-15T15-24-52-374Z.json | 15 + .../session-2026-04-15T15-24-53-380Z.json | 21 + .../session-2026-04-15T15-24-54-425Z.json | 15 + .../session-2026-04-15T15-24-55-432Z.json | 21 + .../session-2026-04-15T15-24-56-483Z.json | 21 + .../session-2026-04-15T15-24-57-525Z.json | 15 + .../session-2026-04-15T15-24-58-563Z.json | 15 + .../session-2026-04-15T15-25-11-864Z.json | 21 + .../session-2026-04-15T15-25-14-683Z.json | 21 + .../session-2026-04-15T15-25-15-731Z.json | 23 + .../session-2026-04-15T15-25-16-780Z.json | 21 + .../session-2026-04-15T16-03-40-304Z.json | 15 + .../session-2026-04-15T16-03-41-383Z.json | 15 + .../session-2026-04-15T16-03-42-418Z.json | 15 + .../session-2026-04-15T16-03-43-469Z.json | 21 + .../session-2026-04-15T16-03-44-500Z.json | 15 + .../session-2026-04-15T16-03-45-523Z.json | 21 + .../session-2026-04-15T16-03-46-551Z.json | 21 + .../session-2026-04-15T16-03-47-619Z.json | 15 + .../session-2026-04-15T16-03-48-682Z.json | 15 + .../session-2026-04-15T16-04-02-106Z.json | 21 + .../session-2026-04-15T16-04-04-959Z.json | 21 + .../session-2026-04-15T16-04-05-979Z.json | 23 + .../session-2026-04-15T16-04-07-046Z.json | 21 + src/core/diagnostic-pipeline.js | 173 +- src/core/project-scanner.js | 1 + src/dashboard.js | 2915 ++++++++++++++--- src/http-server.js | 184 +- src/server.js | 61 +- src/tools.js | 70 + .../session-2026-04-14T23-06-26-532Z.json | 48 + .../session-2026-04-14T23-08-07-969Z.json | 48 + .../session-2026-04-14T23-10-06-483Z.json | 48 + .../session-2026-04-14T23-15-23-985Z.json | 48 + .../session-2026-04-14T23-18-42-542Z.json | 48 + .../session-2026-04-15T10-35-29-566Z.json | 48 + .../session-2026-04-15T15-27-11-802Z.json | 48 + .../session-2026-04-14T23-01-32-494Z.json | 21 + .../session-2026-04-14T23-02-12-429Z.json | 21 + .../session-2026-04-14T23-02-13-274Z.json | 21 + .../session-2026-04-14T23-02-14-277Z.json | 27 + .../session-2026-04-14T23-02-25-097Z.json | 21 + .../session-2026-04-14T23-02-25-940Z.json | 49 + .../session-2026-04-14T23-02-33-929Z.json | 48 + .../session-2026-04-14T23-02-46-760Z.json | 26 + .../session-2026-04-14T23-02-47-719Z.json | 21 + .../session-2026-04-14T23-02-48-571Z.json | 21 + .../session-2026-04-14T23-02-50-313Z.json | 32 + .../session-2026-04-14T23-03-18-816Z.json | 38 + .../session-2026-04-14T23-04-13-125Z.json | 28 + .../session-2026-04-14T23-04-23-091Z.json | 28 + .../session-2026-04-14T23-04-32-734Z.json | 32 + .../session-2026-04-14T23-04-34-190Z.json | 21 + .../session-2026-04-14T23-04-46-840Z.json | 74 + .../session-2026-04-14T23-05-11-868Z.json | 30 + .../session-2026-04-14T23-05-21-527Z.json | 21 + .../session-2026-04-14T23-05-22-430Z.json | 21 + .../session-2026-04-14T23-05-23-528Z.json | 27 + .../session-2026-04-14T23-05-27-168Z.json | 35 + .../session-2026-04-14T23-05-36-120Z.json | 21 + .../session-2026-04-14T23-05-37-254Z.json | 49 + .../session-2026-04-14T23-05-46-604Z.json | 48 + .../session-2026-04-14T23-05-46-869Z.json | 15 + .../session-2026-04-14T23-05-59-833Z.json | 26 + .../session-2026-04-14T23-06-00-793Z.json | 21 + .../session-2026-04-14T23-06-01-673Z.json | 21 + .../session-2026-04-14T23-06-02-973Z.json | 28 + .../session-2026-04-14T23-06-06-773Z.json | 25 + .../session-2026-04-14T23-06-12-463Z.json | 28 + .../session-2026-04-14T23-06-15-444Z.json | 49 + .../session-2026-04-14T23-06-22-263Z.json | 32 + .../session-2026-04-14T23-06-36-454Z.json | 74 + .../session-2026-04-14T23-06-38-265Z.json | 21 + .../session-2026-04-14T23-06-39-513Z.json | 41 + .../session-2026-04-14T23-07-02-725Z.json | 30 + .../session-2026-04-14T23-07-18-545Z.json | 35 + .../session-2026-04-14T23-07-27-624Z.json | 21 + .../session-2026-04-14T23-07-28-649Z.json | 21 + .../session-2026-04-14T23-07-29-965Z.json | 27 + .../session-2026-04-14T23-07-39-157Z.json | 25 + .../session-2026-04-14T23-07-45-149Z.json | 21 + .../session-2026-04-14T23-07-46-271Z.json | 49 + .../session-2026-04-14T23-07-46-740Z.json | 21 + .../session-2026-04-14T23-07-47-958Z.json | 25 + .../session-2026-04-14T23-07-48-819Z.json | 31 + .../session-2026-04-14T23-07-56-033Z.json | 48 + .../session-2026-04-14T23-07-57-183Z.json | 49 + .../session-2026-04-14T23-08-10-510Z.json | 26 + .../session-2026-04-14T23-08-11-581Z.json | 21 + .../session-2026-04-14T23-08-12-442Z.json | 21 + .../session-2026-04-14T23-08-13-819Z.json | 28 + .../session-2026-04-14T23-08-20-160Z.json | 41 + .../session-2026-04-14T23-08-23-395Z.json | 28 + .../session-2026-04-14T23-08-32-563Z.json | 32 + .../session-2026-04-14T23-08-45-662Z.json | 74 + .../session-2026-04-14T23-09-09-496Z.json | 30 + .../session-2026-04-14T23-09-16-352Z.json | 21 + .../session-2026-04-14T23-09-17-364Z.json | 31 + .../session-2026-04-14T23-09-22-915Z.json | 35 + .../session-2026-04-14T23-09-40-755Z.json | 25 + .../session-2026-04-14T23-09-48-057Z.json | 25 + .../session-2026-04-14T23-09-56-448Z.json | 49 + .../session-2026-04-14T23-10-17-918Z.json | 41 + .../session-2026-04-14T23-12-15-779Z.json | 21 + .../session-2026-04-14T23-12-55-272Z.json | 21 + .../session-2026-04-14T23-12-56-080Z.json | 21 + .../session-2026-04-14T23-12-57-087Z.json | 27 + .../session-2026-04-14T23-13-08-118Z.json | 21 + .../session-2026-04-14T23-13-09-038Z.json | 49 + .../session-2026-04-14T23-13-17-073Z.json | 48 + .../session-2026-04-14T23-13-29-730Z.json | 26 + .../session-2026-04-14T23-13-30-722Z.json | 21 + .../session-2026-04-14T23-13-31-530Z.json | 21 + .../session-2026-04-14T23-13-32-804Z.json | 28 + .../session-2026-04-14T23-13-41-478Z.json | 28 + .../session-2026-04-14T23-13-50-047Z.json | 32 + .../session-2026-04-14T23-14-02-975Z.json | 74 + .../session-2026-04-14T23-14-25-804Z.json | 30 + .../session-2026-04-14T23-14-39-491Z.json | 35 + .../session-2026-04-14T23-14-58-823Z.json | 25 + .../session-2026-04-14T23-15-05-843Z.json | 25 + .../session-2026-04-14T23-15-13-581Z.json | 49 + .../session-2026-04-14T23-15-31-042Z.json | 21 + .../session-2026-04-14T23-15-35-843Z.json | 41 + .../session-2026-04-14T23-16-14-406Z.json | 21 + .../session-2026-04-14T23-16-15-289Z.json | 21 + .../session-2026-04-14T23-16-16-301Z.json | 27 + .../session-2026-04-14T23-16-28-639Z.json | 21 + .../session-2026-04-14T23-16-29-549Z.json | 49 + .../session-2026-04-14T23-16-33-200Z.json | 21 + .../session-2026-04-14T23-16-34-192Z.json | 31 + .../session-2026-04-14T23-16-37-859Z.json | 48 + .../session-2026-04-14T23-16-50-916Z.json | 26 + .../session-2026-04-14T23-16-51-917Z.json | 21 + .../session-2026-04-14T23-16-52-735Z.json | 21 + .../session-2026-04-14T23-16-53-969Z.json | 28 + .../session-2026-04-14T23-17-02-587Z.json | 28 + .../session-2026-04-14T23-17-11-750Z.json | 32 + .../session-2026-04-14T23-17-24-867Z.json | 74 + .../session-2026-04-14T23-17-48-270Z.json | 30 + .../session-2026-04-14T23-18-01-411Z.json | 35 + .../session-2026-04-14T23-18-18-608Z.json | 25 + .../session-2026-04-14T23-18-25-270Z.json | 25 + .../session-2026-04-14T23-18-32-649Z.json | 49 + .../session-2026-04-14T23-18-54-074Z.json | 41 + .../session-2026-04-14T23-19-47-693Z.json | 21 + .../session-2026-04-14T23-19-48-707Z.json | 31 + .../session-2026-04-15T10-32-18-061Z.json | 21 + .../session-2026-04-15T10-33-00-734Z.json | 21 + .../session-2026-04-15T10-33-01-691Z.json | 21 + .../session-2026-04-15T10-33-02-651Z.json | 27 + .../session-2026-04-15T10-33-14-099Z.json | 21 + .../session-2026-04-15T10-33-15-107Z.json | 49 + .../session-2026-04-15T10-33-23-482Z.json | 48 + .../session-2026-04-15T10-33-36-291Z.json | 26 + .../session-2026-04-15T10-33-37-365Z.json | 21 + .../session-2026-04-15T10-33-38-343Z.json | 21 + .../session-2026-04-15T10-33-39-745Z.json | 28 + .../session-2026-04-15T10-33-48-763Z.json | 28 + .../session-2026-04-15T10-33-57-954Z.json | 32 + .../session-2026-04-15T10-34-10-789Z.json | 74 + .../session-2026-04-15T10-34-34-100Z.json | 30 + .../session-2026-04-15T10-34-46-869Z.json | 35 + .../session-2026-04-15T10-35-03-727Z.json | 25 + .../session-2026-04-15T10-35-10-907Z.json | 25 + .../session-2026-04-15T10-35-19-170Z.json | 49 + .../session-2026-04-15T10-35-41-642Z.json | 41 + .../session-2026-04-15T10-36-39-729Z.json | 21 + .../session-2026-04-15T10-36-40-848Z.json | 31 + .../session-2026-04-15T10-45-17-517Z.json | 15 + .../session-2026-04-15T10-49-59-846Z.json | 31 + .../session-2026-04-15T11-27-54-592Z.json | 15 + .../session-2026-04-15T11-32-31-446Z.json | 15 + .../session-2026-04-15T11-38-37-882Z.json | 15 + .../session-2026-04-15T11-46-45-777Z.json | 15 + .../session-2026-04-15T15-22-32-422Z.json | 21 + .../session-2026-04-15T15-23-15-339Z.json | 21 + .../session-2026-04-15T15-23-16-777Z.json | 21 + .../session-2026-04-15T15-23-18-129Z.json | 27 + .../session-2026-04-15T15-23-29-606Z.json | 21 + .../session-2026-04-15T15-23-30-538Z.json | 49 + .../session-2026-04-15T15-23-38-438Z.json | 48 + .../session-2026-04-15T15-23-51-689Z.json | 26 + .../session-2026-04-15T15-23-52-737Z.json | 21 + .../session-2026-04-15T15-23-53-547Z.json | 21 + .../session-2026-04-15T15-23-55-338Z.json | 32 + .../session-2026-04-15T15-24-24-960Z.json | 38 + .../session-2026-04-15T15-25-18-816Z.json | 28 + .../session-2026-04-15T15-25-27-771Z.json | 28 + .../session-2026-04-15T15-25-36-880Z.json | 32 + .../session-2026-04-15T15-25-50-371Z.json | 74 + .../session-2026-04-15T15-26-14-308Z.json | 30 + .../session-2026-04-15T15-26-27-552Z.json | 35 + .../session-2026-04-15T15-26-45-473Z.json | 25 + .../session-2026-04-15T15-26-52-401Z.json | 25 + .../session-2026-04-15T15-27-00-495Z.json | 49 + .../session-2026-04-15T15-27-23-170Z.json | 40 + 382 files changed, 11980 insertions(+), 586 deletions(-) create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-43-088Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-44-115Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-45-130Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-46-149Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-47-158Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-48-220Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-49-480Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-50-630Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-54-51-721Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-55-05-056Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-55-07-822Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-55-08-837Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T22-55-09-811Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-43-971Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-45-016Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-46-067Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-47-170Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-48-203Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-49-217Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-50-369Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-51-347Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-03-52-320Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-00-322Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-01-371Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-02-416Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-03-444Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-04-520Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-05-606Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-05-768Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-06-683Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-07-780Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-08-872Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-08-989Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-09-934Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-10-942Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-22-645Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-26-263Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-27-404Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-04-28-550Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-25-183Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-26-320Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-27-465Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-28-613Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-29-736Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-30-829Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-31-828Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-32-912Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-34-024Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-47-636Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-51-061Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-52-120Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-10-53-238Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-38-417Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-39-411Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-40-431Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-41-446Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-42-493Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-43-551Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-44-687Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-45-707Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-11-46-731Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-12-00-105Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-12-03-222Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-12-04-283Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-12-05-402Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-51-982Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-53-055Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-54-170Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-55-333Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-56-491Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-57-538Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-58-686Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-14-59-866Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-15-01-163Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-15-14-781Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-15-17-805Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-15-18-869Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-14T23-15-19-906Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-46-858Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-47-837Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-48-845Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-49-912Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-50-981Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-52-057Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-53-156Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-54-152Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-42-55-212Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-43-08-582Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-43-11-415Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-43-12-444Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T05-43-13-440Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-04-176Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-05-195Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-06-217Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-07-298Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-08-331Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-09-323Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-10-303Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-11-309Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-12-311Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-25-626Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-28-421Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-29-414Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T06-08-30-388Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-45-291Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-46-462Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-47-745Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-48-923Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-50-130Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-51-230Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-52-343Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-53-393Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-31-54-377Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-32-07-614Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-32-10-392Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-32-11-378Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-32-12-357Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-48-787Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-49-909Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-51-093Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-52-294Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-53-820Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-55-125Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-56-313Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-57-419Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-48-58-476Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-49-11-760Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-49-14-489Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-49-15-508Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T10-49-16-519Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-48-850Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-49-859Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-50-877Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-51-908Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-52-921Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-53-965Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-54-962Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-55-943Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-26-56-916Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-27-10-127Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-27-12-867Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-27-13-914Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-27-14-921Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-32-784Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-33-817Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-34-847Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-35-901Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-36-913Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-37-928Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-38-957Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-39-942Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-40-939Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-54-259Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-57-203Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-58-198Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T11-37-59-194Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-12-967Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-13-976Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-15-013Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-16-008Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-16-997Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-18-026Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-19-015Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-20-017Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-21-019Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-34-343Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-37-076Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-38-124Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-13-39-136Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-21-59-954Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-01-197Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-02-257Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-03-263Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-04-243Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-05-299Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-06-321Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-07-346Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-08-376Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-21-742Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-24-663Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-25-687Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-22-26-773Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-50-268Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-51-309Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-52-374Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-53-380Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-54-425Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-55-432Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-56-483Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-57-525Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-24-58-563Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-25-11-864Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-25-14-683Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-25-15-731Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T15-25-16-780Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-40-304Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-41-383Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-42-418Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-43-469Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-44-500Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-45-523Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-46-551Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-47-619Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-03-48-682Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-04-02-106Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-04-04-959Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-04-05-979Z.json create mode 100644 .pos-supervisor/sessions/session-2026-04-15T16-04-07-046Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-14T23-06-26-532Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-14T23-08-07-969Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-14T23-10-06-483Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-14T23-15-23-985Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-14T23-18-42-542Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-15T10-35-29-566Z.json create mode 100644 tests/fixtures/broken-project/.pos-supervisor/sessions/session-2026-04-15T15-27-11-802Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-01-32-494Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-12-429Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-13-274Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-14-277Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-25-097Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-25-940Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-33-929Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-46-760Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-47-719Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-48-571Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-02-50-313Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-03-18-816Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-04-13-125Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-04-23-091Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-04-32-734Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-04-34-190Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-04-46-840Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-11-868Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-21-527Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-22-430Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-23-528Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-27-168Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-36-120Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-37-254Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-46-604Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-46-869Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-05-59-833Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-00-793Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-01-673Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-02-973Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-06-773Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-12-463Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-15-444Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-22-263Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-36-454Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-38-265Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-06-39-513Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-02-725Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-18-545Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-27-624Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-28-649Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-29-965Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-39-157Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-45-149Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-46-271Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-46-740Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-47-958Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-48-819Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-56-033Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-07-57-183Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-10-510Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-11-581Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-12-442Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-13-819Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-20-160Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-23-395Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-32-563Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-08-45-662Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-09-496Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-16-352Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-17-364Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-22-915Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-40-755Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-48-057Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-09-56-448Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-10-17-918Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-12-15-779Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-12-55-272Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-12-56-080Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-12-57-087Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-08-118Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-09-038Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-17-073Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-29-730Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-30-722Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-31-530Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-32-804Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-41-478Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-13-50-047Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-14-02-975Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-14-25-804Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-14-39-491Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-14-58-823Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-15-05-843Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-15-13-581Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-15-31-042Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-15-35-843Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-14-406Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-15-289Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-16-301Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-28-639Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-29-549Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-33-200Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-34-192Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-37-859Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-50-916Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-51-917Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-52-735Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-16-53-969Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-17-02-587Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-17-11-750Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-17-24-867Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-17-48-270Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-18-01-411Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-18-18-608Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-18-25-270Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-18-32-649Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-18-54-074Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-19-47-693Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-14T23-19-48-707Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-32-18-061Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-00-734Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-01-691Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-02-651Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-14-099Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-15-107Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-23-482Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-36-291Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-37-365Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-38-343Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-39-745Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-48-763Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-33-57-954Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-34-10-789Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-34-34-100Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-34-46-869Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-35-03-727Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-35-10-907Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-35-19-170Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-35-41-642Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-36-39-729Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-36-40-848Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-45-17-517Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T10-49-59-846Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T11-27-54-592Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T11-32-31-446Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T11-38-37-882Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T11-46-45-777Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-22-32-422Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-15-339Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-16-777Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-18-129Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-29-606Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-30-538Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-38-438Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-51-689Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-52-737Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-53-547Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-23-55-338Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-24-24-960Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-25-18-816Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-25-27-771Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-25-36-880Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-25-50-371Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-26-14-308Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-26-27-552Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-26-45-473Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-26-52-401Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-27-00-495Z.json create mode 100644 tests/fixtures/project/.pos-supervisor/sessions/session-2026-04-15T15-27-23-170Z.json diff --git a/.gitignore b/.gitignore index e2700c0..c84b27e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ node_modules/ *.jsonl .mcp.json CLAUDE.md +./pos-supervisor diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-43-088Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-43-088Z.json new file mode 100644 index 0000000..6c44d4e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-43-088Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-43-088Z", + "startedAt": "2026-04-14T22:54:43.042Z", + "endedAt": "2026-04-14T22:54:43.305Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-44-115Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-44-115Z.json new file mode 100644 index 0000000..eced7ee --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-44-115Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-44-115Z", + "startedAt": "2026-04-14T22:54:44.070Z", + "endedAt": "2026-04-14T22:54:44.345Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-45-130Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-45-130Z.json new file mode 100644 index 0000000..9368e26 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-45-130Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-45-130Z", + "startedAt": "2026-04-14T22:54:45.091Z", + "endedAt": "2026-04-14T22:54:45.351Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-46-149Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-46-149Z.json new file mode 100644 index 0000000..b3cc63b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-46-149Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-54-46-149Z", + "startedAt": "2026-04-14T22:54:46.105Z", + "endedAt": "2026-04-14T22:54:46.363Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 26 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-47-158Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-47-158Z.json new file mode 100644 index 0000000..3ece8b3 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-47-158Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-47-158Z", + "startedAt": "2026-04-14T22:54:47.113Z", + "endedAt": "2026-04-14T22:54:47.388Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-48-220Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-48-220Z.json new file mode 100644 index 0000000..d29a758 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-48-220Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-54-48-220Z", + "startedAt": "2026-04-14T22:54:48.166Z", + "endedAt": "2026-04-14T22:54:48.448Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-49-480Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-49-480Z.json new file mode 100644 index 0000000..cd5eb68 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-49-480Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-54-49-480Z", + "startedAt": "2026-04-14T22:54:49.424Z", + "endedAt": "2026-04-14T22:54:49.707Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 29 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-50-630Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-50-630Z.json new file mode 100644 index 0000000..10ebb1f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-50-630Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-50-630Z", + "startedAt": "2026-04-14T22:54:50.590Z", + "endedAt": "2026-04-14T22:54:50.859Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-54-51-721Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-54-51-721Z.json new file mode 100644 index 0000000..79ab089 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-54-51-721Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T22-54-51-721Z", + "startedAt": "2026-04-14T22:54:51.674Z", + "endedAt": "2026-04-14T22:54:51.946Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-55-05-056Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-55-05-056Z.json new file mode 100644 index 0000000..ddb13b4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-55-05-056Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-55-05-056Z", + "startedAt": "2026-04-14T22:55:05.015Z", + "endedAt": "2026-04-14T22:55:05.119Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-55-07-822Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-55-07-822Z.json new file mode 100644 index 0000000..f8528c9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-55-07-822Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-55-07-822Z", + "startedAt": "2026-04-14T22:55:07.780Z", + "endedAt": "2026-04-14T22:55:08.046Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-55-08-837Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-55-08-837Z.json new file mode 100644 index 0000000..4838a7e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-55-08-837Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T22-55-08-837Z", + "startedAt": "2026-04-14T22:55:08.793Z", + "endedAt": "2026-04-14T22:55:09.054Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T22-55-09-811Z.json b/.pos-supervisor/sessions/session-2026-04-14T22-55-09-811Z.json new file mode 100644 index 0000000..55ccfa5 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T22-55-09-811Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T22-55-09-811Z", + "startedAt": "2026-04-14T22:55:09.773Z", + "endedAt": "2026-04-14T22:55:10.032Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-43-971Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-43-971Z.json new file mode 100644 index 0000000..eddedee --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-43-971Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-43-971Z", + "startedAt": "2026-04-14T23:03:43.930Z", + "endedAt": "2026-04-14T23:03:44.188Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-45-016Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-45-016Z.json new file mode 100644 index 0000000..9c267e5 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-45-016Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-45-016Z", + "startedAt": "2026-04-14T23:03:44.976Z", + "endedAt": "2026-04-14T23:03:45.242Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-46-067Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-46-067Z.json new file mode 100644 index 0000000..1692df5 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-46-067Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-46-067Z", + "startedAt": "2026-04-14T23:03:46.018Z", + "endedAt": "2026-04-14T23:03:46.292Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-47-170Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-47-170Z.json new file mode 100644 index 0000000..d3b478c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-47-170Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-03-47-170Z", + "startedAt": "2026-04-14T23:03:47.126Z", + "endedAt": "2026-04-14T23:03:47.391Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-48-203Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-48-203Z.json new file mode 100644 index 0000000..1673ebc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-48-203Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-48-203Z", + "startedAt": "2026-04-14T23:03:48.164Z", + "endedAt": "2026-04-14T23:03:48.424Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-49-217Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-49-217Z.json new file mode 100644 index 0000000..e58d3f2 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-49-217Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-03-49-217Z", + "startedAt": "2026-04-14T23:03:49.174Z", + "endedAt": "2026-04-14T23:03:49.440Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 29 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-50-369Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-50-369Z.json new file mode 100644 index 0000000..104d87e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-50-369Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-03-50-369Z", + "startedAt": "2026-04-14T23:03:50.331Z", + "endedAt": "2026-04-14T23:03:50.592Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-51-347Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-51-347Z.json new file mode 100644 index 0000000..6d83d64 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-51-347Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-51-347Z", + "startedAt": "2026-04-14T23:03:51.310Z", + "endedAt": "2026-04-14T23:03:51.564Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-03-52-320Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-03-52-320Z.json new file mode 100644 index 0000000..da003f1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-03-52-320Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-03-52-320Z", + "startedAt": "2026-04-14T23:03:52.275Z", + "endedAt": "2026-04-14T23:03:52.546Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-00-322Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-00-322Z.json new file mode 100644 index 0000000..d6edea3 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-00-322Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-00-322Z", + "startedAt": "2026-04-14T23:04:00.273Z", + "endedAt": "2026-04-14T23:04:00.547Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-01-371Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-01-371Z.json new file mode 100644 index 0000000..67d8cc9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-01-371Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-01-371Z", + "startedAt": "2026-04-14T23:04:01.326Z", + "endedAt": "2026-04-14T23:04:01.604Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-02-416Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-02-416Z.json new file mode 100644 index 0000000..34d7592 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-02-416Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-02-416Z", + "startedAt": "2026-04-14T23:04:02.375Z", + "endedAt": "2026-04-14T23:04:02.637Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-03-444Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-03-444Z.json new file mode 100644 index 0000000..56abd19 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-03-444Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-03-444Z", + "startedAt": "2026-04-14T23:04:03.397Z", + "endedAt": "2026-04-14T23:04:03.672Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 33 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-04-520Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-04-520Z.json new file mode 100644 index 0000000..dfc5022 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-04-520Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-04-520Z", + "startedAt": "2026-04-14T23:04:04.480Z", + "endedAt": "2026-04-14T23:04:04.747Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-05-606Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-05-606Z.json new file mode 100644 index 0000000..395e784 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-05-606Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-05-606Z", + "startedAt": "2026-04-14T23:04:05.558Z", + "endedAt": "2026-04-14T23:04:05.832Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 37 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-05-768Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-05-768Z.json new file mode 100644 index 0000000..804ecca --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-05-768Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-05-768Z", + "startedAt": "2026-04-14T23:04:05.720Z", + "endedAt": "2026-04-14T23:04:05.849Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 3 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-06-683Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-06-683Z.json new file mode 100644 index 0000000..9fceafa --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-06-683Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-06-683Z", + "startedAt": "2026-04-14T23:04:06.643Z", + "endedAt": "2026-04-14T23:04:06.908Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 32 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-07-780Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-07-780Z.json new file mode 100644 index 0000000..e59944c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-07-780Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-07-780Z", + "startedAt": "2026-04-14T23:04:07.731Z", + "endedAt": "2026-04-14T23:04:08.004Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-08-872Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-08-872Z.json new file mode 100644 index 0000000..062cdcd --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-08-872Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-08-872Z", + "startedAt": "2026-04-14T23:04:08.824Z", + "endedAt": "2026-04-14T23:04:09.098Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-08-989Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-08-989Z.json new file mode 100644 index 0000000..482fba1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-08-989Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-04-08-989Z", + "startedAt": "2026-04-14T23:04:08.942Z", + "endedAt": "2026-04-14T23:04:09.209Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-09-934Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-09-934Z.json new file mode 100644 index 0000000..bcdbfef --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-09-934Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T23-04-09-934Z", + "startedAt": "2026-04-14T23:04:09.890Z", + "endedAt": "2026-04-14T23:04:10.160Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-10-942Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-10-942Z.json new file mode 100644 index 0000000..458d44c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-10-942Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-10-942Z", + "startedAt": "2026-04-14T23:04:10.897Z", + "endedAt": "2026-04-14T23:04:11.165Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-22-645Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-22-645Z.json new file mode 100644 index 0000000..89403e6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-22-645Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-22-645Z", + "startedAt": "2026-04-14T23:04:22.587Z", + "endedAt": "2026-04-14T23:04:22.729Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 3 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-26-263Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-26-263Z.json new file mode 100644 index 0000000..08e8e78 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-26-263Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-26-263Z", + "startedAt": "2026-04-14T23:04:26.217Z", + "endedAt": "2026-04-14T23:04:26.490Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-27-404Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-27-404Z.json new file mode 100644 index 0000000..3bf2a7c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-27-404Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T23-04-27-404Z", + "startedAt": "2026-04-14T23:04:27.357Z", + "endedAt": "2026-04-14T23:04:27.625Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-04-28-550Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-04-28-550Z.json new file mode 100644 index 0000000..301fe3a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-04-28-550Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-04-28-550Z", + "startedAt": "2026-04-14T23:04:28.494Z", + "endedAt": "2026-04-14T23:04:28.788Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-25-183Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-25-183Z.json new file mode 100644 index 0000000..750f91a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-25-183Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-25-183Z", + "startedAt": "2026-04-14T23:10:25.140Z", + "endedAt": "2026-04-14T23:10:25.403Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-26-320Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-26-320Z.json new file mode 100644 index 0000000..f401c39 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-26-320Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-26-320Z", + "startedAt": "2026-04-14T23:10:26.270Z", + "endedAt": "2026-04-14T23:10:26.546Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-27-465Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-27-465Z.json new file mode 100644 index 0000000..175ec5b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-27-465Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-27-465Z", + "startedAt": "2026-04-14T23:10:27.419Z", + "endedAt": "2026-04-14T23:10:27.682Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-28-613Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-28-613Z.json new file mode 100644 index 0000000..48635c9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-28-613Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-28-613Z", + "startedAt": "2026-04-14T23:10:28.564Z", + "endedAt": "2026-04-14T23:10:28.835Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-29-736Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-29-736Z.json new file mode 100644 index 0000000..ba5a6eb --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-29-736Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-29-736Z", + "startedAt": "2026-04-14T23:10:29.697Z", + "endedAt": "2026-04-14T23:10:29.958Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-30-829Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-30-829Z.json new file mode 100644 index 0000000..841d0f1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-30-829Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-30-829Z", + "startedAt": "2026-04-14T23:10:30.782Z", + "endedAt": "2026-04-14T23:10:31.057Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 39 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-31-828Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-31-828Z.json new file mode 100644 index 0000000..5babab7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-31-828Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-31-828Z", + "startedAt": "2026-04-14T23:10:31.782Z", + "endedAt": "2026-04-14T23:10:32.048Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-32-912Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-32-912Z.json new file mode 100644 index 0000000..99965fe --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-32-912Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-32-912Z", + "startedAt": "2026-04-14T23:10:32.869Z", + "endedAt": "2026-04-14T23:10:33.132Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-34-024Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-34-024Z.json new file mode 100644 index 0000000..dae7531 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-34-024Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-10-34-024Z", + "startedAt": "2026-04-14T23:10:33.969Z", + "endedAt": "2026-04-14T23:10:34.247Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-47-636Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-47-636Z.json new file mode 100644 index 0000000..dbbeec7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-47-636Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-47-636Z", + "startedAt": "2026-04-14T23:10:47.592Z", + "endedAt": "2026-04-14T23:10:47.705Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-51-061Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-51-061Z.json new file mode 100644 index 0000000..2fa419c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-51-061Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-51-061Z", + "startedAt": "2026-04-14T23:10:51.015Z", + "endedAt": "2026-04-14T23:10:51.283Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-52-120Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-52-120Z.json new file mode 100644 index 0000000..2df309b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-52-120Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T23-10-52-120Z", + "startedAt": "2026-04-14T23:10:52.079Z", + "endedAt": "2026-04-14T23:10:52.348Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-10-53-238Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-10-53-238Z.json new file mode 100644 index 0000000..583dd5d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-10-53-238Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-10-53-238Z", + "startedAt": "2026-04-14T23:10:53.192Z", + "endedAt": "2026-04-14T23:10:53.464Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-38-417Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-38-417Z.json new file mode 100644 index 0000000..3283c32 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-38-417Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-38-417Z", + "startedAt": "2026-04-14T23:11:38.372Z", + "endedAt": "2026-04-14T23:11:38.642Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-39-411Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-39-411Z.json new file mode 100644 index 0000000..c798292 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-39-411Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-39-411Z", + "startedAt": "2026-04-14T23:11:39.367Z", + "endedAt": "2026-04-14T23:11:39.639Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-40-431Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-40-431Z.json new file mode 100644 index 0000000..533b77c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-40-431Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-40-431Z", + "startedAt": "2026-04-14T23:11:40.390Z", + "endedAt": "2026-04-14T23:11:40.653Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-41-446Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-41-446Z.json new file mode 100644 index 0000000..d30aca7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-41-446Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-11-41-446Z", + "startedAt": "2026-04-14T23:11:41.396Z", + "endedAt": "2026-04-14T23:11:41.674Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 38 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-42-493Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-42-493Z.json new file mode 100644 index 0000000..71ecc9e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-42-493Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-42-493Z", + "startedAt": "2026-04-14T23:11:42.444Z", + "endedAt": "2026-04-14T23:11:42.718Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-43-551Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-43-551Z.json new file mode 100644 index 0000000..d879ac1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-43-551Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-11-43-551Z", + "startedAt": "2026-04-14T23:11:43.505Z", + "endedAt": "2026-04-14T23:11:43.779Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 32 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-44-687Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-44-687Z.json new file mode 100644 index 0000000..9fb48c6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-44-687Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-11-44-687Z", + "startedAt": "2026-04-14T23:11:44.635Z", + "endedAt": "2026-04-14T23:11:44.913Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 31 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-45-707Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-45-707Z.json new file mode 100644 index 0000000..4c33c3f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-45-707Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-45-707Z", + "startedAt": "2026-04-14T23:11:45.663Z", + "endedAt": "2026-04-14T23:11:45.926Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-11-46-731Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-11-46-731Z.json new file mode 100644 index 0000000..66ecf95 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-11-46-731Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-11-46-731Z", + "startedAt": "2026-04-14T23:11:46.674Z", + "endedAt": "2026-04-14T23:11:46.968Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-12-00-105Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-12-00-105Z.json new file mode 100644 index 0000000..ac01557 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-12-00-105Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-12-00-105Z", + "startedAt": "2026-04-14T23:12:00.043Z", + "endedAt": "2026-04-14T23:12:00.194Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-12-03-222Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-12-03-222Z.json new file mode 100644 index 0000000..9a0afbf --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-12-03-222Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-12-03-222Z", + "startedAt": "2026-04-14T23:12:03.183Z", + "endedAt": "2026-04-14T23:12:03.445Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-12-04-283Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-12-04-283Z.json new file mode 100644 index 0000000..783ebd2 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-12-04-283Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T23-12-04-283Z", + "startedAt": "2026-04-14T23:12:04.237Z", + "endedAt": "2026-04-14T23:12:04.514Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-12-05-402Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-12-05-402Z.json new file mode 100644 index 0000000..cd349d1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-12-05-402Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-12-05-402Z", + "startedAt": "2026-04-14T23:12:05.357Z", + "endedAt": "2026-04-14T23:12:05.631Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-51-982Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-51-982Z.json new file mode 100644 index 0000000..73fa765 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-51-982Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-14-51-982Z", + "startedAt": "2026-04-14T23:14:51.938Z", + "endedAt": "2026-04-14T23:14:52.214Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-53-055Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-53-055Z.json new file mode 100644 index 0000000..22a0d34 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-53-055Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-14-53-055Z", + "startedAt": "2026-04-14T23:14:53.005Z", + "endedAt": "2026-04-14T23:14:53.283Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-54-170Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-54-170Z.json new file mode 100644 index 0000000..f7fcaa6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-54-170Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-14-54-170Z", + "startedAt": "2026-04-14T23:14:54.120Z", + "endedAt": "2026-04-14T23:14:54.397Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-55-333Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-55-333Z.json new file mode 100644 index 0000000..1e0793e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-55-333Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-14-55-333Z", + "startedAt": "2026-04-14T23:14:55.293Z", + "endedAt": "2026-04-14T23:14:55.561Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 39 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-56-491Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-56-491Z.json new file mode 100644 index 0000000..effa742 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-56-491Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-14-56-491Z", + "startedAt": "2026-04-14T23:14:56.446Z", + "endedAt": "2026-04-14T23:14:56.720Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-57-538Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-57-538Z.json new file mode 100644 index 0000000..ea01f0a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-57-538Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-14-57-538Z", + "startedAt": "2026-04-14T23:14:57.498Z", + "endedAt": "2026-04-14T23:14:57.762Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 26 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-58-686Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-58-686Z.json new file mode 100644 index 0000000..428e075 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-58-686Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-14-58-686Z", + "startedAt": "2026-04-14T23:14:58.631Z", + "endedAt": "2026-04-14T23:14:58.904Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 35 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-14-59-866Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-14-59-866Z.json new file mode 100644 index 0000000..b628f66 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-14-59-866Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-14-59-866Z", + "startedAt": "2026-04-14T23:14:59.813Z", + "endedAt": "2026-04-14T23:15:00.090Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-15-01-163Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-15-01-163Z.json new file mode 100644 index 0000000..0ce64e4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-15-01-163Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-14T23-15-01-163Z", + "startedAt": "2026-04-14T23:15:01.112Z", + "endedAt": "2026-04-14T23:15:01.385Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-15-14-781Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-15-14-781Z.json new file mode 100644 index 0000000..4bd9d8a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-15-14-781Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-15-14-781Z", + "startedAt": "2026-04-14T23:15:14.730Z", + "endedAt": "2026-04-14T23:15:14.845Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-15-17-805Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-15-17-805Z.json new file mode 100644 index 0000000..5ac31c4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-15-17-805Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-15-17-805Z", + "startedAt": "2026-04-14T23:15:17.754Z", + "endedAt": "2026-04-14T23:15:18.033Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-15-18-869Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-15-18-869Z.json new file mode 100644 index 0000000..45c9f3c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-15-18-869Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-14T23-15-18-869Z", + "startedAt": "2026-04-14T23:15:18.828Z", + "endedAt": "2026-04-14T23:15:19.096Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-14T23-15-19-906Z.json b/.pos-supervisor/sessions/session-2026-04-14T23-15-19-906Z.json new file mode 100644 index 0000000..8045f10 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-14T23-15-19-906Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-14T23-15-19-906Z", + "startedAt": "2026-04-14T23:15:19.867Z", + "endedAt": "2026-04-14T23:15:20.127Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-46-858Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-46-858Z.json new file mode 100644 index 0000000..591c795 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-46-858Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-46-858Z", + "startedAt": "2026-04-15T05:42:46.817Z", + "endedAt": "2026-04-15T05:42:47.076Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-47-837Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-47-837Z.json new file mode 100644 index 0000000..dee3c31 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-47-837Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-47-837Z", + "startedAt": "2026-04-15T05:42:47.797Z", + "endedAt": "2026-04-15T05:42:48.062Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-48-845Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-48-845Z.json new file mode 100644 index 0000000..f9b6a37 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-48-845Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-48-845Z", + "startedAt": "2026-04-15T05:42:48.804Z", + "endedAt": "2026-04-15T05:42:49.067Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-49-912Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-49-912Z.json new file mode 100644 index 0000000..2677af8 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-49-912Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-42-49-912Z", + "startedAt": "2026-04-15T05:42:49.870Z", + "endedAt": "2026-04-15T05:42:50.134Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-50-981Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-50-981Z.json new file mode 100644 index 0000000..cee7a8f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-50-981Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-50-981Z", + "startedAt": "2026-04-15T05:42:50.934Z", + "endedAt": "2026-04-15T05:42:51.211Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-52-057Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-52-057Z.json new file mode 100644 index 0000000..d1d5dd5 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-52-057Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-42-52-057Z", + "startedAt": "2026-04-15T05:42:52.005Z", + "endedAt": "2026-04-15T05:42:52.283Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 33 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-53-156Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-53-156Z.json new file mode 100644 index 0000000..df54518 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-53-156Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-42-53-156Z", + "startedAt": "2026-04-15T05:42:53.112Z", + "endedAt": "2026-04-15T05:42:53.379Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 37 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-54-152Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-54-152Z.json new file mode 100644 index 0000000..bc1d791 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-54-152Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-54-152Z", + "startedAt": "2026-04-15T05:42:54.111Z", + "endedAt": "2026-04-15T05:42:54.374Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-42-55-212Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-42-55-212Z.json new file mode 100644 index 0000000..34d21b6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-42-55-212Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T05-42-55-212Z", + "startedAt": "2026-04-15T05:42:55.166Z", + "endedAt": "2026-04-15T05:42:55.429Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-43-08-582Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-43-08-582Z.json new file mode 100644 index 0000000..6c07147 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-43-08-582Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-43-08-582Z", + "startedAt": "2026-04-15T05:43:08.540Z", + "endedAt": "2026-04-15T05:43:08.636Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-43-11-415Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-43-11-415Z.json new file mode 100644 index 0000000..b6f4601 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-43-11-415Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-43-11-415Z", + "startedAt": "2026-04-15T05:43:11.366Z", + "endedAt": "2026-04-15T05:43:11.648Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-43-12-444Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-43-12-444Z.json new file mode 100644 index 0000000..7937168 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-43-12-444Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T05-43-12-444Z", + "startedAt": "2026-04-15T05:43:12.398Z", + "endedAt": "2026-04-15T05:43:12.662Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T05-43-13-440Z.json b/.pos-supervisor/sessions/session-2026-04-15T05-43-13-440Z.json new file mode 100644 index 0000000..ea3af10 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T05-43-13-440Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T05-43-13-440Z", + "startedAt": "2026-04-15T05:43:13.398Z", + "endedAt": "2026-04-15T05:43:13.660Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-04-176Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-04-176Z.json new file mode 100644 index 0000000..08bb92c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-04-176Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-04-176Z", + "startedAt": "2026-04-15T06:08:04.125Z", + "endedAt": "2026-04-15T06:08:04.398Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-05-195Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-05-195Z.json new file mode 100644 index 0000000..802e06b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-05-195Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-05-195Z", + "startedAt": "2026-04-15T06:08:05.154Z", + "endedAt": "2026-04-15T06:08:05.411Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-06-217Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-06-217Z.json new file mode 100644 index 0000000..8076361 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-06-217Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-06-217Z", + "startedAt": "2026-04-15T06:08:06.176Z", + "endedAt": "2026-04-15T06:08:06.442Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-07-298Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-07-298Z.json new file mode 100644 index 0000000..d8a7777 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-07-298Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-07-298Z", + "startedAt": "2026-04-15T06:08:07.254Z", + "endedAt": "2026-04-15T06:08:07.515Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 31 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-08-331Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-08-331Z.json new file mode 100644 index 0000000..376e682 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-08-331Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-08-331Z", + "startedAt": "2026-04-15T06:08:08.292Z", + "endedAt": "2026-04-15T06:08:08.553Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-09-323Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-09-323Z.json new file mode 100644 index 0000000..35b8800 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-09-323Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-09-323Z", + "startedAt": "2026-04-15T06:08:09.281Z", + "endedAt": "2026-04-15T06:08:09.545Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 32 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-10-303Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-10-303Z.json new file mode 100644 index 0000000..061c069 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-10-303Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-10-303Z", + "startedAt": "2026-04-15T06:08:10.261Z", + "endedAt": "2026-04-15T06:08:10.524Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 27 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-11-309Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-11-309Z.json new file mode 100644 index 0000000..1fe989e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-11-309Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-11-309Z", + "startedAt": "2026-04-15T06:08:11.266Z", + "endedAt": "2026-04-15T06:08:11.523Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-12-311Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-12-311Z.json new file mode 100644 index 0000000..24b98c7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-12-311Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T06-08-12-311Z", + "startedAt": "2026-04-15T06:08:12.272Z", + "endedAt": "2026-04-15T06:08:12.530Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-25-626Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-25-626Z.json new file mode 100644 index 0000000..871fbee --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-25-626Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-25-626Z", + "startedAt": "2026-04-15T06:08:25.588Z", + "endedAt": "2026-04-15T06:08:25.684Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-28-421Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-28-421Z.json new file mode 100644 index 0000000..ca705b4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-28-421Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-28-421Z", + "startedAt": "2026-04-15T06:08:28.378Z", + "endedAt": "2026-04-15T06:08:28.649Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-29-414Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-29-414Z.json new file mode 100644 index 0000000..1e913fb --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-29-414Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T06-08-29-414Z", + "startedAt": "2026-04-15T06:08:29.375Z", + "endedAt": "2026-04-15T06:08:29.635Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T06-08-30-388Z.json b/.pos-supervisor/sessions/session-2026-04-15T06-08-30-388Z.json new file mode 100644 index 0000000..605df43 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T06-08-30-388Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T06-08-30-388Z", + "startedAt": "2026-04-15T06:08:30.349Z", + "endedAt": "2026-04-15T06:08:30.611Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-45-291Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-45-291Z.json new file mode 100644 index 0000000..af5f348 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-45-291Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-45-291Z", + "startedAt": "2026-04-15T10:31:45.246Z", + "endedAt": "2026-04-15T10:31:45.512Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-46-462Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-46-462Z.json new file mode 100644 index 0000000..31afb5d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-46-462Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-46-462Z", + "startedAt": "2026-04-15T10:31:46.405Z", + "endedAt": "2026-04-15T10:31:46.697Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-47-745Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-47-745Z.json new file mode 100644 index 0000000..db88125 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-47-745Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-47-745Z", + "startedAt": "2026-04-15T10:31:47.693Z", + "endedAt": "2026-04-15T10:31:47.978Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-48-923Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-48-923Z.json new file mode 100644 index 0000000..dddd318 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-48-923Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-31-48-923Z", + "startedAt": "2026-04-15T10:31:48.877Z", + "endedAt": "2026-04-15T10:31:49.151Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 39 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-50-130Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-50-130Z.json new file mode 100644 index 0000000..a06212d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-50-130Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-50-130Z", + "startedAt": "2026-04-15T10:31:50.088Z", + "endedAt": "2026-04-15T10:31:50.355Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-51-230Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-51-230Z.json new file mode 100644 index 0000000..230d583 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-51-230Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-31-51-230Z", + "startedAt": "2026-04-15T10:31:51.180Z", + "endedAt": "2026-04-15T10:31:51.456Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-52-343Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-52-343Z.json new file mode 100644 index 0000000..67a6d3c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-52-343Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-31-52-343Z", + "startedAt": "2026-04-15T10:31:52.301Z", + "endedAt": "2026-04-15T10:31:52.558Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 25 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-53-393Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-53-393Z.json new file mode 100644 index 0000000..c022abc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-53-393Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-53-393Z", + "startedAt": "2026-04-15T10:31:53.349Z", + "endedAt": "2026-04-15T10:31:53.617Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-31-54-377Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-31-54-377Z.json new file mode 100644 index 0000000..20572cd --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-31-54-377Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-31-54-377Z", + "startedAt": "2026-04-15T10:31:54.337Z", + "endedAt": "2026-04-15T10:31:54.597Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-32-07-614Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-32-07-614Z.json new file mode 100644 index 0000000..2f4b4e9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-32-07-614Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-32-07-614Z", + "startedAt": "2026-04-15T10:32:07.575Z", + "endedAt": "2026-04-15T10:32:07.679Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-32-10-392Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-32-10-392Z.json new file mode 100644 index 0000000..3ab1049 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-32-10-392Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-32-10-392Z", + "startedAt": "2026-04-15T10:32:10.350Z", + "endedAt": "2026-04-15T10:32:10.614Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-32-11-378Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-32-11-378Z.json new file mode 100644 index 0000000..90ff76f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-32-11-378Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T10-32-11-378Z", + "startedAt": "2026-04-15T10:32:11.340Z", + "endedAt": "2026-04-15T10:32:11.600Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-32-12-357Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-32-12-357Z.json new file mode 100644 index 0000000..3e16b12 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-32-12-357Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-32-12-357Z", + "startedAt": "2026-04-15T10:32:12.318Z", + "endedAt": "2026-04-15T10:32:12.579Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-48-787Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-48-787Z.json new file mode 100644 index 0000000..178ec95 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-48-787Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-48-787Z", + "startedAt": "2026-04-15T10:48:48.735Z", + "endedAt": "2026-04-15T10:48:49.010Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-49-909Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-49-909Z.json new file mode 100644 index 0000000..1d9f21b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-49-909Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-49-909Z", + "startedAt": "2026-04-15T10:48:49.861Z", + "endedAt": "2026-04-15T10:48:50.138Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-51-093Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-51-093Z.json new file mode 100644 index 0000000..2c3a3a2 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-51-093Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-51-093Z", + "startedAt": "2026-04-15T10:48:51.043Z", + "endedAt": "2026-04-15T10:48:51.322Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-52-294Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-52-294Z.json new file mode 100644 index 0000000..4b52564 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-52-294Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-48-52-294Z", + "startedAt": "2026-04-15T10:48:52.248Z", + "endedAt": "2026-04-15T10:48:52.524Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 42 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-53-820Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-53-820Z.json new file mode 100644 index 0000000..bc3429f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-53-820Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-53-820Z", + "startedAt": "2026-04-15T10:48:53.732Z", + "endedAt": "2026-04-15T10:48:54.056Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-55-125Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-55-125Z.json new file mode 100644 index 0000000..c57ed31 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-55-125Z.json @@ -0,0 +1,26 @@ +{ + "id": "session-2026-04-15T10-48-55-125Z", + "startedAt": "2026-04-15T10:48:55.069Z", + "endedAt": "2026-04-15T10:48:55.351Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 55 + }, + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 4 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-56-313Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-56-313Z.json new file mode 100644 index 0000000..933732c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-56-313Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-48-56-313Z", + "startedAt": "2026-04-15T10:48:56.259Z", + "endedAt": "2026-04-15T10:48:56.547Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 43 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-57-419Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-57-419Z.json new file mode 100644 index 0000000..38687ee --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-57-419Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-57-419Z", + "startedAt": "2026-04-15T10:48:57.373Z", + "endedAt": "2026-04-15T10:48:57.645Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-48-58-476Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-48-58-476Z.json new file mode 100644 index 0000000..e421a64 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-48-58-476Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T10-48-58-476Z", + "startedAt": "2026-04-15T10:48:58.427Z", + "endedAt": "2026-04-15T10:48:58.696Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-49-11-760Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-49-11-760Z.json new file mode 100644 index 0000000..62e1bb6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-49-11-760Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-49-11-760Z", + "startedAt": "2026-04-15T10:49:11.721Z", + "endedAt": "2026-04-15T10:49:11.818Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-49-14-489Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-49-14-489Z.json new file mode 100644 index 0000000..11b4928 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-49-14-489Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-49-14-489Z", + "startedAt": "2026-04-15T10:49:14.450Z", + "endedAt": "2026-04-15T10:49:14.709Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-49-15-508Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-49-15-508Z.json new file mode 100644 index 0000000..46cc6c0 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-49-15-508Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T10-49-15-508Z", + "startedAt": "2026-04-15T10:49:15.464Z", + "endedAt": "2026-04-15T10:49:15.725Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T10-49-16-519Z.json b/.pos-supervisor/sessions/session-2026-04-15T10-49-16-519Z.json new file mode 100644 index 0000000..f9b58d1 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T10-49-16-519Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T10-49-16-519Z", + "startedAt": "2026-04-15T10:49:16.479Z", + "endedAt": "2026-04-15T10:49:16.741Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-48-850Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-48-850Z.json new file mode 100644 index 0000000..9558afc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-48-850Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-48-850Z", + "startedAt": "2026-04-15T11:26:48.802Z", + "endedAt": "2026-04-15T11:26:49.075Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-49-859Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-49-859Z.json new file mode 100644 index 0000000..5c76051 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-49-859Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-49-859Z", + "startedAt": "2026-04-15T11:26:49.819Z", + "endedAt": "2026-04-15T11:26:50.081Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-50-877Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-50-877Z.json new file mode 100644 index 0000000..0e20c1d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-50-877Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-50-877Z", + "startedAt": "2026-04-15T11:26:50.837Z", + "endedAt": "2026-04-15T11:26:51.098Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-51-908Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-51-908Z.json new file mode 100644 index 0000000..00880b9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-51-908Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-26-51-908Z", + "startedAt": "2026-04-15T11:26:51.867Z", + "endedAt": "2026-04-15T11:26:52.130Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-52-921Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-52-921Z.json new file mode 100644 index 0000000..cd4dfd4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-52-921Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-52-921Z", + "startedAt": "2026-04-15T11:26:52.873Z", + "endedAt": "2026-04-15T11:26:53.145Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-53-965Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-53-965Z.json new file mode 100644 index 0000000..df06982 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-53-965Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-26-53-965Z", + "startedAt": "2026-04-15T11:26:53.927Z", + "endedAt": "2026-04-15T11:26:54.185Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-54-962Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-54-962Z.json new file mode 100644 index 0000000..eb5ad68 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-54-962Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-26-54-962Z", + "startedAt": "2026-04-15T11:26:54.922Z", + "endedAt": "2026-04-15T11:26:55.184Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-55-943Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-55-943Z.json new file mode 100644 index 0000000..20df6bf --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-55-943Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-55-943Z", + "startedAt": "2026-04-15T11:26:55.904Z", + "endedAt": "2026-04-15T11:26:56.163Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-26-56-916Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-26-56-916Z.json new file mode 100644 index 0000000..f93092c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-26-56-916Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-26-56-916Z", + "startedAt": "2026-04-15T11:26:56.874Z", + "endedAt": "2026-04-15T11:26:57.129Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-27-10-127Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-27-10-127Z.json new file mode 100644 index 0000000..c924ed9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-27-10-127Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-27-10-127Z", + "startedAt": "2026-04-15T11:27:10.079Z", + "endedAt": "2026-04-15T11:27:10.187Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-27-12-867Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-27-12-867Z.json new file mode 100644 index 0000000..d5526bf --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-27-12-867Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-27-12-867Z", + "startedAt": "2026-04-15T11:27:12.824Z", + "endedAt": "2026-04-15T11:27:13.092Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-27-13-914Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-27-13-914Z.json new file mode 100644 index 0000000..62ca13d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-27-13-914Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T11-27-13-914Z", + "startedAt": "2026-04-15T11:27:13.875Z", + "endedAt": "2026-04-15T11:27:14.138Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-27-14-921Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-27-14-921Z.json new file mode 100644 index 0000000..47a9ada --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-27-14-921Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-27-14-921Z", + "startedAt": "2026-04-15T11:27:14.883Z", + "endedAt": "2026-04-15T11:27:15.143Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-32-784Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-32-784Z.json new file mode 100644 index 0000000..667f4cc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-32-784Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-32-784Z", + "startedAt": "2026-04-15T11:37:32.743Z", + "endedAt": "2026-04-15T11:37:33.004Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-33-817Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-33-817Z.json new file mode 100644 index 0000000..efb6e54 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-33-817Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-33-817Z", + "startedAt": "2026-04-15T11:37:33.774Z", + "endedAt": "2026-04-15T11:37:34.042Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-34-847Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-34-847Z.json new file mode 100644 index 0000000..5de9b04 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-34-847Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-34-847Z", + "startedAt": "2026-04-15T11:37:34.808Z", + "endedAt": "2026-04-15T11:37:35.067Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-35-901Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-35-901Z.json new file mode 100644 index 0000000..53c2c57 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-35-901Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-35-901Z", + "startedAt": "2026-04-15T11:37:35.865Z", + "endedAt": "2026-04-15T11:37:36.126Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 28 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-36-913Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-36-913Z.json new file mode 100644 index 0000000..da4a8f7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-36-913Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-36-913Z", + "startedAt": "2026-04-15T11:37:36.870Z", + "endedAt": "2026-04-15T11:37:37.143Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-37-928Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-37-928Z.json new file mode 100644 index 0000000..b9b27c0 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-37-928Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-37-928Z", + "startedAt": "2026-04-15T11:37:37.889Z", + "endedAt": "2026-04-15T11:37:38.152Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-38-957Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-38-957Z.json new file mode 100644 index 0000000..f0daf8e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-38-957Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-38-957Z", + "startedAt": "2026-04-15T11:37:38.917Z", + "endedAt": "2026-04-15T11:37:39.178Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-39-942Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-39-942Z.json new file mode 100644 index 0000000..547da7b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-39-942Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-39-942Z", + "startedAt": "2026-04-15T11:37:39.902Z", + "endedAt": "2026-04-15T11:37:40.163Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-40-939Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-40-939Z.json new file mode 100644 index 0000000..2ada808 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-40-939Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T11-37-40-939Z", + "startedAt": "2026-04-15T11:37:40.899Z", + "endedAt": "2026-04-15T11:37:41.160Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-54-259Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-54-259Z.json new file mode 100644 index 0000000..05d627c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-54-259Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-54-259Z", + "startedAt": "2026-04-15T11:37:54.217Z", + "endedAt": "2026-04-15T11:37:54.318Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-57-203Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-57-203Z.json new file mode 100644 index 0000000..f6dee1e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-57-203Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-57-203Z", + "startedAt": "2026-04-15T11:37:57.160Z", + "endedAt": "2026-04-15T11:37:57.422Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-58-198Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-58-198Z.json new file mode 100644 index 0000000..77b0a3f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-58-198Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T11-37-58-198Z", + "startedAt": "2026-04-15T11:37:58.155Z", + "endedAt": "2026-04-15T11:37:58.424Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T11-37-59-194Z.json b/.pos-supervisor/sessions/session-2026-04-15T11-37-59-194Z.json new file mode 100644 index 0000000..8063072 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T11-37-59-194Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T11-37-59-194Z", + "startedAt": "2026-04-15T11:37:59.150Z", + "endedAt": "2026-04-15T11:37:59.415Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-12-967Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-12-967Z.json new file mode 100644 index 0000000..c178993 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-12-967Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-12-967Z", + "startedAt": "2026-04-15T15:13:12.916Z", + "endedAt": "2026-04-15T15:13:13.193Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-13-976Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-13-976Z.json new file mode 100644 index 0000000..3c007ad --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-13-976Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-13-976Z", + "startedAt": "2026-04-15T15:13:13.938Z", + "endedAt": "2026-04-15T15:13:14.197Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-15-013Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-15-013Z.json new file mode 100644 index 0000000..b799b34 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-15-013Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-15-013Z", + "startedAt": "2026-04-15T15:13:14.966Z", + "endedAt": "2026-04-15T15:13:15.229Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-16-008Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-16-008Z.json new file mode 100644 index 0000000..93cc147 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-16-008Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-16-008Z", + "startedAt": "2026-04-15T15:13:15.964Z", + "endedAt": "2026-04-15T15:13:16.226Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 25 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-16-997Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-16-997Z.json new file mode 100644 index 0000000..d7adeba --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-16-997Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-16-997Z", + "startedAt": "2026-04-15T15:13:16.957Z", + "endedAt": "2026-04-15T15:13:17.222Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-18-026Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-18-026Z.json new file mode 100644 index 0000000..86d3acd --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-18-026Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-18-026Z", + "startedAt": "2026-04-15T15:13:17.981Z", + "endedAt": "2026-04-15T15:13:18.249Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 32 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-19-015Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-19-015Z.json new file mode 100644 index 0000000..0be43a4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-19-015Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-19-015Z", + "startedAt": "2026-04-15T15:13:18.975Z", + "endedAt": "2026-04-15T15:13:19.235Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 25 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-20-017Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-20-017Z.json new file mode 100644 index 0000000..e5e297b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-20-017Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-20-017Z", + "startedAt": "2026-04-15T15:13:19.977Z", + "endedAt": "2026-04-15T15:13:20.236Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-21-019Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-21-019Z.json new file mode 100644 index 0000000..7e37592 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-21-019Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-13-21-019Z", + "startedAt": "2026-04-15T15:13:20.978Z", + "endedAt": "2026-04-15T15:13:21.242Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-34-343Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-34-343Z.json new file mode 100644 index 0000000..c2205e9 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-34-343Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-34-343Z", + "startedAt": "2026-04-15T15:13:34.298Z", + "endedAt": "2026-04-15T15:13:34.399Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-37-076Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-37-076Z.json new file mode 100644 index 0000000..f4681d4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-37-076Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-37-076Z", + "startedAt": "2026-04-15T15:13:37.033Z", + "endedAt": "2026-04-15T15:13:37.298Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-38-124Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-38-124Z.json new file mode 100644 index 0000000..1ee4e25 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-38-124Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T15-13-38-124Z", + "startedAt": "2026-04-15T15:13:38.078Z", + "endedAt": "2026-04-15T15:13:38.350Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-13-39-136Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-13-39-136Z.json new file mode 100644 index 0000000..4c0742f --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-13-39-136Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-13-39-136Z", + "startedAt": "2026-04-15T15:13:39.096Z", + "endedAt": "2026-04-15T15:13:39.358Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-21-59-954Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-21-59-954Z.json new file mode 100644 index 0000000..78f8417 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-21-59-954Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-21-59-954Z", + "startedAt": "2026-04-15T15:21:59.875Z", + "endedAt": "2026-04-15T15:22:00.207Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-01-197Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-01-197Z.json new file mode 100644 index 0000000..c6d3349 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-01-197Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-22-01-197Z", + "startedAt": "2026-04-15T15:22:01.153Z", + "endedAt": "2026-04-15T15:22:01.422Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-02-257Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-02-257Z.json new file mode 100644 index 0000000..9338b73 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-02-257Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-22-02-257Z", + "startedAt": "2026-04-15T15:22:02.218Z", + "endedAt": "2026-04-15T15:22:02.480Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-03-263Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-03-263Z.json new file mode 100644 index 0000000..6fb1be6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-03-263Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-03-263Z", + "startedAt": "2026-04-15T15:22:03.223Z", + "endedAt": "2026-04-15T15:22:03.486Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-04-243Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-04-243Z.json new file mode 100644 index 0000000..fb282cc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-04-243Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-22-04-243Z", + "startedAt": "2026-04-15T15:22:04.202Z", + "endedAt": "2026-04-15T15:22:04.467Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-05-299Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-05-299Z.json new file mode 100644 index 0000000..76ac6ba --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-05-299Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-05-299Z", + "startedAt": "2026-04-15T15:22:05.258Z", + "endedAt": "2026-04-15T15:22:05.526Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 36 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-06-321Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-06-321Z.json new file mode 100644 index 0000000..75fb60b --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-06-321Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-06-321Z", + "startedAt": "2026-04-15T15:22:06.278Z", + "endedAt": "2026-04-15T15:22:06.535Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 33 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-07-346Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-07-346Z.json new file mode 100644 index 0000000..5cc34c8 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-07-346Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-22-07-346Z", + "startedAt": "2026-04-15T15:22:07.305Z", + "endedAt": "2026-04-15T15:22:07.570Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-08-376Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-08-376Z.json new file mode 100644 index 0000000..05bf027 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-08-376Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-22-08-376Z", + "startedAt": "2026-04-15T15:22:08.335Z", + "endedAt": "2026-04-15T15:22:08.597Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-21-742Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-21-742Z.json new file mode 100644 index 0000000..a24a35c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-21-742Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-21-742Z", + "startedAt": "2026-04-15T15:22:21.701Z", + "endedAt": "2026-04-15T15:22:21.807Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-24-663Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-24-663Z.json new file mode 100644 index 0000000..ca8a904 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-24-663Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-24-663Z", + "startedAt": "2026-04-15T15:22:24.621Z", + "endedAt": "2026-04-15T15:22:24.888Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-25-687Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-25-687Z.json new file mode 100644 index 0000000..c492347 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-25-687Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T15-22-25-687Z", + "startedAt": "2026-04-15T15:22:25.644Z", + "endedAt": "2026-04-15T15:22:25.911Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-22-26-773Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-22-26-773Z.json new file mode 100644 index 0000000..40d976a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-22-26-773Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-22-26-773Z", + "startedAt": "2026-04-15T15:22:26.728Z", + "endedAt": "2026-04-15T15:22:26.999Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-50-268Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-50-268Z.json new file mode 100644 index 0000000..965bc94 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-50-268Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-50-268Z", + "startedAt": "2026-04-15T15:24:50.224Z", + "endedAt": "2026-04-15T15:24:50.495Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-51-309Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-51-309Z.json new file mode 100644 index 0000000..d215a49 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-51-309Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-51-309Z", + "startedAt": "2026-04-15T15:24:51.268Z", + "endedAt": "2026-04-15T15:24:51.532Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-52-374Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-52-374Z.json new file mode 100644 index 0000000..0ae427c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-52-374Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-52-374Z", + "startedAt": "2026-04-15T15:24:52.333Z", + "endedAt": "2026-04-15T15:24:52.596Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-53-380Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-53-380Z.json new file mode 100644 index 0000000..04ebe77 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-53-380Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-24-53-380Z", + "startedAt": "2026-04-15T15:24:53.340Z", + "endedAt": "2026-04-15T15:24:53.602Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 30 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-54-425Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-54-425Z.json new file mode 100644 index 0000000..27de671 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-54-425Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-54-425Z", + "startedAt": "2026-04-15T15:24:54.386Z", + "endedAt": "2026-04-15T15:24:54.650Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-55-432Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-55-432Z.json new file mode 100644 index 0000000..533a9fc --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-55-432Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-24-55-432Z", + "startedAt": "2026-04-15T15:24:55.391Z", + "endedAt": "2026-04-15T15:24:55.658Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 26 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-56-483Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-56-483Z.json new file mode 100644 index 0000000..2fe5bff --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-56-483Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-24-56-483Z", + "startedAt": "2026-04-15T15:24:56.444Z", + "endedAt": "2026-04-15T15:24:56.704Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 32 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-57-525Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-57-525Z.json new file mode 100644 index 0000000..a59d86a --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-57-525Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-57-525Z", + "startedAt": "2026-04-15T15:24:57.481Z", + "endedAt": "2026-04-15T15:24:57.751Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-24-58-563Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-24-58-563Z.json new file mode 100644 index 0000000..1e55d90 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-24-58-563Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T15-24-58-563Z", + "startedAt": "2026-04-15T15:24:58.519Z", + "endedAt": "2026-04-15T15:24:58.778Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-25-11-864Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-25-11-864Z.json new file mode 100644 index 0000000..a543e01 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-25-11-864Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-25-11-864Z", + "startedAt": "2026-04-15T15:25:11.824Z", + "endedAt": "2026-04-15T15:25:11.929Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-25-14-683Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-25-14-683Z.json new file mode 100644 index 0000000..2e12c30 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-25-14-683Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-25-14-683Z", + "startedAt": "2026-04-15T15:25:14.640Z", + "endedAt": "2026-04-15T15:25:14.914Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-25-15-731Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-25-15-731Z.json new file mode 100644 index 0000000..d59580d --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-25-15-731Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T15-25-15-731Z", + "startedAt": "2026-04-15T15:25:15.691Z", + "endedAt": "2026-04-15T15:25:15.964Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T15-25-16-780Z.json b/.pos-supervisor/sessions/session-2026-04-15T15-25-16-780Z.json new file mode 100644 index 0000000..42abcc7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T15-25-16-780Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T15-25-16-780Z", + "startedAt": "2026-04-15T15:25:16.737Z", + "endedAt": "2026-04-15T15:25:17.006Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-40-304Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-40-304Z.json new file mode 100644 index 0000000..32320d5 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-40-304Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-40-304Z", + "startedAt": "2026-04-15T16:03:40.261Z", + "endedAt": "2026-04-15T16:03:40.526Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-41-383Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-41-383Z.json new file mode 100644 index 0000000..571b20e --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-41-383Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-41-383Z", + "startedAt": "2026-04-15T16:03:41.346Z", + "endedAt": "2026-04-15T16:03:41.611Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-42-418Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-42-418Z.json new file mode 100644 index 0000000..fab04ca --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-42-418Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-42-418Z", + "startedAt": "2026-04-15T16:03:42.373Z", + "endedAt": "2026-04-15T16:03:42.647Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-43-469Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-43-469Z.json new file mode 100644 index 0000000..4cfa89c --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-43-469Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-03-43-469Z", + "startedAt": "2026-04-15T16:03:43.430Z", + "endedAt": "2026-04-15T16:03:43.692Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 27 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-44-500Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-44-500Z.json new file mode 100644 index 0000000..9117ac0 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-44-500Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-44-500Z", + "startedAt": "2026-04-15T16:03:44.459Z", + "endedAt": "2026-04-15T16:03:44.723Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-45-523Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-45-523Z.json new file mode 100644 index 0000000..8806178 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-45-523Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-03-45-523Z", + "startedAt": "2026-04-15T16:03:45.481Z", + "endedAt": "2026-04-15T16:03:45.748Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 1, + "errors": 0, + "totalMs": 34 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-46-551Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-46-551Z.json new file mode 100644 index 0000000..0465bc7 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-46-551Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-03-46-551Z", + "startedAt": "2026-04-15T16:03:46.504Z", + "endedAt": "2026-04-15T16:03:46.780Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "load_development_guide": { + "calls": 1, + "errors": 0, + "totalMs": 37 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-47-619Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-47-619Z.json new file mode 100644 index 0000000..6adcc46 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-47-619Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-47-619Z", + "startedAt": "2026-04-15T16:03:47.575Z", + "endedAt": "2026-04-15T16:03:47.841Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-03-48-682Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-03-48-682Z.json new file mode 100644 index 0000000..639a115 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-03-48-682Z.json @@ -0,0 +1,15 @@ +{ + "id": "session-2026-04-15T16-03-48-682Z", + "startedAt": "2026-04-15T16:03:48.642Z", + "endedAt": "2026-04-15T16:03:48.904Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 0, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": {} +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-04-02-106Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-04-02-106Z.json new file mode 100644 index 0000000..b081628 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-04-02-106Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-04-02-106Z", + "startedAt": "2026-04-15T16:04:02.064Z", + "endedAt": "2026-04-15T16:04:02.178Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 2, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "domain_guide": { + "calls": 2, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-04-04-959Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-04-04-959Z.json new file mode 100644 index 0000000..31790f6 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-04-04-959Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-04-04-959Z", + "startedAt": "2026-04-15T16:04:04.919Z", + "endedAt": "2026-04-15T16:04:05.184Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "server_status": { + "calls": 1, + "errors": 0, + "totalMs": 0 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-04-05-979Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-04-05-979Z.json new file mode 100644 index 0000000..f6b0ea4 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-04-05-979Z.json @@ -0,0 +1,23 @@ +{ + "id": "session-2026-04-15T16-04-05-979Z", + "startedAt": "2026-04-15T16:04:05.940Z", + "endedAt": "2026-04-15T16:04:06.202Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 0, + "filesValidated": 1, + "checkFrequency": { + "InputError": 1 + }, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "validate_code": { + "calls": 1, + "errors": 0, + "totalMs": 1 + } + } +} \ No newline at end of file diff --git a/.pos-supervisor/sessions/session-2026-04-15T16-04-07-046Z.json b/.pos-supervisor/sessions/session-2026-04-15T16-04-07-046Z.json new file mode 100644 index 0000000..9188773 --- /dev/null +++ b/.pos-supervisor/sessions/session-2026-04-15T16-04-07-046Z.json @@ -0,0 +1,21 @@ +{ + "id": "session-2026-04-15T16-04-07-046Z", + "startedAt": "2026-04-15T16:04:06.998Z", + "endedAt": "2026-04-15T16:04:07.272Z", + "projectDir": "/home/ecgtheow/Work/pos-ai-tools/pos-mcp", + "version": "0.5.2", + "toolCalls": 1, + "toolErrors": 1, + "filesValidated": 0, + "checkFrequency": {}, + "checkEffectiveness": {}, + "hintEffectiveness": {}, + "scaffoldRuns": 0, + "stats": { + "analyze_project": { + "calls": 1, + "errors": 1, + "totalMs": 2 + } + } +} \ No newline at end of file diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js index fc4122c..f2524bf 100644 --- a/src/core/diagnostic-pipeline.js +++ b/src/core/diagnostic-pipeline.js @@ -37,6 +37,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'; import { join } from 'node:path'; +import yaml from 'js-yaml'; import { getKnownModulesMissingDocs } from './knowledge-loader.js'; import { buildAssetIndex, resolveAssetPath } from './asset-index.js'; import { buildTranslationIndex } from './translation-index.js'; @@ -66,80 +67,97 @@ export function runDiagnosticPipeline(result, opts) { projectDir, } = opts; + // Pipeline trace (D2 — pipeline step inspector). Each step records what changed. + const trace = []; + function traceStep(name, fn) { + const eBefore = result.errors.length; + const wBefore = result.warnings.length; + fn(); + const eRemoved = eBefore - result.errors.length; + const wRemoved = wBefore - result.warnings.length; + const eAdded = result.errors.length - (eBefore - eRemoved); + trace.push({ + step: name, + errorsRemoved: eRemoved, + warningsRemoved: wRemoved, + errorsAfter: result.errors.length, + warningsAfter: result.warnings.length, + }); + } + // Accumulate suppression summaries into one info diagnostic — the agent sees a single line. const suppressionNotes = []; + // 0. Apply user-defined suppressions from .pos-supervisor-ignore.yml (A3) + if (projectDir) { + traceStep('userSuppressions', () => applyUserSuppressions(result, filePath, projectDir)); + } + // 1. Suppress UndefinedObject for declared @param names if (docParamNames.size > 0) { - suppressDocParams(result, docParamNames); + traceStep('suppressDocParams', () => suppressDocParams(result, docParamNames)); } // 2. Suppress UnusedDocParam when param is used as named argument if (docParamNames.size > 0) { - suppressUnusedDocParams(result, docParamNames, content); + traceStep('suppressUnusedDocParams', () => suppressUnusedDocParams(result, docParamNames, content)); } // 3. Elevate Shopify contamination from warning to error - elevateShopify(result); + traceStep('elevateShopify', () => elevateShopify(result)); // 4. Deduplicate MissingRenderPartialArguments + MetadataParamsCheck - deduplicateArgChecks(result); + traceStep('deduplicateArgChecks', () => deduplicateArgChecks(result)); // 5. Suppress MetadataParamsCheck when the called target has no {% doc %} block. - // The LSP infers required params from usage patterns when no contract is declared, - // producing false positives for every optional param. Module partials (modules/*) - // are always treated as undocumented (they are excluded from lint by config AND - // overwhelmingly lack doc blocks in practice). App partials/commands/queries are - // confirmed by reading the target file from disk — if it has no {% doc %}, we - // suppress and emit an advisory info pointing at the root fix (add {% doc %}). - suppressUndocumentedTargetParams(result, content, projectDir); + traceStep('suppressUndocumentedTargetParams', () => suppressUndocumentedTargetParams(result, content, projectDir)); // 6. Suppress required-param diagnostics whose target partial defaults the param. - // The target's {% doc %} declared it required, but its body does `| default:`, - // so callers that omit the param still receive a valid value. This covers the - // common pattern where authors forgot to bracket the @param name. - suppressRequiredParamsWithDefault(result, content, projectDir); + traceStep('suppressRequiredParamsWithDefault', () => suppressRequiredParamsWithDefault(result, content, projectDir)); // 7. Suppress DeprecatedTag for module helper includes - suppressModuleHelpers(result, content); + traceStep('suppressModuleHelpers', () => suppressModuleHelpers(result, content)); - // 8. Suppress OrphanedPartial for commands/queries and for partials in - // multi-file creation plans (callers may be pending and not on disk yet). - suppressOrphanedPartial(result, filePath, pendingFiles, pendingPages); + // 8. Suppress OrphanedPartial for commands/queries and pending plans + traceStep('suppressOrphanedPartial', () => suppressOrphanedPartial(result, filePath, pendingFiles, pendingPages)); - // 8. Suppress MissingPartial for pending files + // 9. Suppress MissingPartial for pending files if (pendingFiles.length > 0) { - const n = suppressByPending(result, { - check: 'MissingPartial', - pendingSet: buildPendingPartialNames(pendingFiles), - extractKey: (d) => d.message?.match(/['"]([^'"]+)['"]/)?.[1] ?? null, + traceStep('suppressPendingPartials', () => { + const n = suppressByPending(result, { + check: 'MissingPartial', + pendingSet: buildPendingPartialNames(pendingFiles), + extractKey: (d) => d.message?.match(/['"]([^'"]+)['"]/)?.[1] ?? null, + }); + if (n > 0) suppressionNotes.push(`${n} MissingPartial(s) for pending files`); }); - if (n > 0) suppressionNotes.push(`${n} MissingPartial(s) for pending files`); } - // 9. Suppress MissingPage for pending pages + // 10. Suppress MissingPage for pending pages if (pendingPages.length > 0) { - const n = suppressByPending(result, { - check: 'MissingPage', - pendingSet: buildPendingPageKeys(pendingPages), - extractKey: (d) => { - // MissingPage messages look like: Page 'blog_posts/show' not found - // or: Missing page at slug 'blog_posts' - const m = d.message?.match(/['"]([^'"]+)['"]/); - return m ? m[1] : null; - }, + traceStep('suppressPendingPages', () => { + const n = suppressByPending(result, { + check: 'MissingPage', + pendingSet: buildPendingPageKeys(pendingPages), + extractKey: (d) => { + const m = d.message?.match(/['"]([^'"]+)['"]/); + return m ? m[1] : null; + }, + }); + if (n > 0) suppressionNotes.push(`${n} MissingPage(s) for pending pages`); }); - if (n > 0) suppressionNotes.push(`${n} MissingPage(s) for pending pages`); } - // 10. Suppress TranslationKeyExists for pending translations + // 11. Suppress TranslationKeyExists for pending translations if (pendingTranslations.length > 0) { - const n = suppressByPending(result, { - check: 'TranslationKeyExists', - pendingSet: new Set(pendingTranslations), - extractKey: (d) => d.message?.match(/['"]([^'"]+)['"]/)?.[1] ?? null, + traceStep('suppressPendingTranslations', () => { + const n = suppressByPending(result, { + check: 'TranslationKeyExists', + pendingSet: new Set(pendingTranslations), + extractKey: (d) => d.message?.match(/['"]([^'"]+)['"]/)?.[1] ?? null, + }); + if (n > 0) suppressionNotes.push(`${n} TranslationKeyExists for pending translations`); }); - if (n > 0) suppressionNotes.push(`${n} TranslationKeyExists for pending translations`); } if (suppressionNotes.length > 0) { @@ -150,44 +168,69 @@ export function runDiagnosticPipeline(result, opts) { }); } - // 11. Verify MissingAsset against filesystem + // 12. Verify MissingAsset against filesystem if (projectDir) { - verifyMissingAssets(result, projectDir); + traceStep('verifyMissingAssets', () => verifyMissingAssets(result, projectDir)); } - // 12. Verify TranslationKeyExists against filesystem. The LSP's translation - // cache lags behind disk just like its asset cache — after the agent - // writes a key to app/translations/.yml the LSP keeps reporting - // "key not found" until it re-indexes. Cross-check against the real - // YAML files so the agent does not need to pass `pending_translations` - // for keys that already exist on disk. + // 13. Verify TranslationKeyExists against filesystem if (projectDir) { - verifyTranslationKeysOnDisk(result, projectDir); + traceStep('verifyTranslationKeysOnDisk', () => verifyTranslationKeysOnDisk(result, projectDir)); } - // 13. Verify MissingPage against filesystem. validate_code analyses one - // file at a time, so any link in a partial pointing to a route defined - // in OTHER pages fires MissingPage. Cross-check against the real page - // files (slug from frontmatter or path-derived) so a header partial - // linking to /notes does not flag the route as missing when - // app/views/pages/notes/index.html.liquid clearly exists. + // 14. Verify MissingPage against filesystem if (projectDir) { - verifyPageRoutesOnDisk(result, projectDir); + traceStep('verifyPageRoutesOnDisk', () => verifyPageRoutesOnDisk(result, projectDir)); } - // 14. Verify OrphanedPartial against filesystem. validate_code analyses - // one file at a time, so the checker has no cross-file render graph. - // After scaffold(write:true) writes all files and clears pending state, - // the checker still reports OrphanedPartial because its index hasn't - // re-indexed the new pages yet. Cross-check by scanning all .liquid - // files on disk for a render/function reference to this partial. + // 15. Verify OrphanedPartial against filesystem if (projectDir) { - verifyOrphanedPartialOnDisk(result, filePath, projectDir); + traceStep('verifyOrphanedPartialOnDisk', () => verifyOrphanedPartialOnDisk(result, filePath, projectDir)); } + + // Attach pipeline trace for dashboard inspector (D2) + result._pipelineTrace = trace; } // ── Individual filters ────────────────────────────────────────────────────── +function applyUserSuppressions(result, filePath, projectDir) { + const suppressFile = join(projectDir, '.pos-supervisor-ignore.yml'); + if (!existsSync(suppressFile)) return; + let rules; + try { + const parsed = yaml.load(readFileSync(suppressFile, 'utf-8')); + rules = parsed?.suppressions; + } catch { return; } + if (!Array.isArray(rules) || rules.length === 0) return; + + const matchRule = (d) => rules.some(r => { + if (r.check !== d.check) return false; + if (r.file_pattern) { + if (r.file_pattern.includes('*')) { + const re = new RegExp('^' + r.file_pattern.replace(/\*/g, '.*') + '$'); + if (!re.test(filePath)) return false; + } else if (!filePath.includes(r.file_pattern)) { + return false; + } + } + return true; + }); + + const errBefore = result.errors.length; + const warnBefore = result.warnings.length; + result.errors = result.errors.filter(d => !matchRule(d)); + result.warnings = result.warnings.filter(d => !matchRule(d)); + const suppressed = (errBefore - result.errors.length) + (warnBefore - result.warnings.length); + if (suppressed > 0) { + result.infos.push({ + check: 'pos-supervisor:UserSuppressed', + severity: 'info', + message: `Suppressed ${suppressed} diagnostic(s) via .pos-supervisor-ignore.yml`, + }); + } +} + function suppressDocParams(result, docParamNames) { const match = (diag) => { if (diag.check !== 'UndefinedObject') return false; diff --git a/src/core/project-scanner.js b/src/core/project-scanner.js index 0aa310a..6ceb6f9 100644 --- a/src/core/project-scanner.js +++ b/src/core/project-scanner.js @@ -111,6 +111,7 @@ export async function scanProject(projectDir) { queries, pages, partials, + layouts, translations, assets, summary: { diff --git a/src/dashboard.js b/src/dashboard.js index 9c88ea9..fbbf6f0 100644 --- a/src/dashboard.js +++ b/src/dashboard.js @@ -3,12 +3,12 @@ * Served at GET /dashboard. * * Features: - * - Real-time via SSE (no polling for activity) - * - Timeline strip: visual tool call sequence with duration as width - * - File validation map: per-file error state grid - * - Compliance checklist: workflow health at a glance - * - Activity table: file_path + error/warning counts in detail column - * - Stats, Playground, Knowledge browser, LSP controls + * - Real-time via SSE (no polling for activity) + * - Timeline strip: visual tool call sequence with duration as width + * - File validation map: per-file error state grid + * - Compliance checklist: workflow health at a glance + * - Activity table: file_path + error/warning counts in detail column + * - Stats, Playground, Knowledge browser, LSP controls */ export function buildDashboardHtml() { @@ -20,308 +20,626 @@ export function buildDashboardHtml() { pos-supervisor
+

pos-supervisor

— @@ -329,26 +647,36 @@ export function buildDashboardHtml() {
-
LSPwarming up
-
pos-clichecking
-
tools—
-
version—
-
calls0
-
errors0
-
connecting
+
+ HEALTH : +
+ + + + + — +
+
+
LSP : WAIT
+
POS-CLI : WAIT
+
TOOLS : —
+
VER : —
+
CALLS : 0
+
ERR : 0
+
+
CONNECTING
Overview
+
Activity
Explorer
-
Routes
Health
-
Activity
-
Stats
-
Playground
-
Knowledge
-
POS-CLI
+
Tool Insights
+
Tool Lab
LSP
+
POS-CLI
+
@@ -372,7 +700,7 @@ export function buildDashboardHtml() {
-

Error Patterns (this session) ↻

+

Error Patterns (SESSION) ↻

no validate_code calls yet
@@ -383,38 +711,101 @@ export function buildDashboardHtml() { - + +
-
- - -
-
-
Click Refresh or switch to this tab to load project data.
-
- -
-
- -
-
Click Refresh to load route data.
+
+

Project Map

+
Runs project_map — vertical slices (schema → GraphQL → business logic → pages).
+
+ + +
+
+
Execute FETCH PROJECT MAP to load resources.
+
+ + + + + +
+

Routes & Lifecycle

+
Execute FETCH PROJECT MAP above to load route tables.
+
+ +
+

Dependency Impact Tree

+
Click a file to see what it depends on and what depends on it. Colored by validation state — fixing red files unblocks everything that references them.
+
+ + +
+ +
- +
-
- - -
-
Click Refresh to load project health data.
+ +
+

Project Analysis

+
Runs analyze_project for stuck files, dead code, integrity, orphans, cycles. Pair with the Project Map in the Explorer tab to interpret findings in context.
+
+ + +
+
Execute RUN ANALYSIS to load project health data.
+
+ +
+

Suppressions

+
Rules written to .pos-supervisor-ignore.yml. The diagnostic pipeline drops matching checks before enrichment.
+
LOADING SUPPRESSIONS...
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+ +
+
- +
-

Timeline

+

Timeline

@@ -428,29 +819,29 @@ export function buildDashboardHtml() {
-
- - - - -
- - - - - - - - - - - - -
TimeToolFile / DetailIssuesDurationStatus
loading…
-
+
+

Call Log

+
+ + + + +
+ + + + + + + + + + + + +
TimeToolFile / DetailIssuesDurationStatus
awaiting entries…
+
- -

Tool Usage

@@ -458,51 +849,27 @@ export function buildDashboardHtml() {
no calls yet
+

Check Frequency

no validate_code calls yet
-
- -
-
-
-

Select Tool

-
loading…
-
-
-
- — - - -
-
- - +
+

Session History

+
Previous sessions are persisted to .pos-supervisor/sessions/. Click SAVE CURRENT to snapshot now, or LOAD SESSIONS to compare past runs side-by-side.
+
+ + +
-
-
+
CLICK LOAD SESSIONS TO FETCH SESSION HISTORY.
+
+ - -
-
-
-

Hints

-
loading…
-
-
- 
Select a hint to view its content.
-
-
+
@@ -518,7 +885,7 @@ export function buildDashboardHtml() {
- +
@@ -540,7 +907,7 @@ export function buildDashboardHtml() {
- +
@@ -552,6 +919,120 @@ export function buildDashboardHtml() {
+ +
+
+ + +
+
+
+
Diagnostic Effectiveness
+
For every check the LSP fires, this shows how often a later validation makes it go away. LOW FIX RATE = the agent sees the error but doesn't fix it — the hint/fix text is probably wrong or missing. Action: improve the hint in src/data/hints/<check>.md.
+
No validate_code calls yet — effectiveness data appears after files are validated multiple times.
+
+
+
Hint Effectiveness
+
Counts how many times enrich_error was called for a check, and how many of those calls led to the error being fixed on the next validation. LOW CONVERSION = agent read the hint but didn't act on it. Action: rewrite the hint to be more directive.
+
No hint data yet — call enrich_error on a few errors first.
+
+
+
Per-File Diagnostic Diff
+
For each file validated more than once, shows what changed between runs: RESOLVED checks, NEW checks, STILL PRESENT. Use it to see if the last edit helped or made things worse.
+
No files with multiple validations yet.
+
+
+
Knowledge Gaps
+
Lists LSP checks that fired in this session but have no hint file in src/data/hints/. Agents got an error message with no guidance on how to fix it. Action: add a hint file for each listed check.
+
Loading…
+
+
+
Workflow Patterns
+
Common tool-call sequences observed in this session (e.g. project_map → scaffold → validate_intent → validate_code). Confirms whether agents are following the intended workflow or taking shortcuts.
+
No tool calls yet.
+
+
+
Scaffold Quality
+
Every scaffold call is scored on: files generated, conflicts, and whether the follow-up validate_intent passed. LOW SCORE = scaffold produced output that didn't match intent. Action: improve the scaffold template or the validator's ontology.
+
No scaffold calls in this session.
+
+
+
Pipeline Inspector
+
Per-file trace through the diagnostic-pipeline — shows how many errors/warnings each step removed. Use it to find inactive steps (never triggered → candidates for removal) and over-eager steps (suppressing too much). Click a file header to expand the trace.
+
No pipeline trace data yet.
+
+
+
Knowledge Library
+
The hint files in src/data/hints/ rendered into the hint field of every enriched diagnostic. Use this to review what agents will actually see when a check fires.
+
+
+

Hints

+
loading…
+
+
+ 
Select a hint to view its content.
+
+
+
+
+ + +
+
+ Every tool exposed by this server — description, input schema, live usage stats, and an executor. Select a tool to see its docs and run it; toggle Live Diagnostic Console to validate arbitrary or project content without wiring params. +
+ +
+ +
+ + +
+
+

Tools

+
LOADING...
+
+
+
+ 
SELECT A TOOL ON THE LEFT TO VIEW DOCS, SESSION STATS, AND RUN IT.
+
+ +
+
+
+
@@ -560,25 +1041,29 @@ export function buildDashboardHtml() {
Status
-
initialising
+
WAIT
pos-cli
-
checking
+
WAIT
- +
-

LSP Events (this session)

+

Daemon Log (SESSION)

no events yet
+ +
+ + +Logo +``` + +### User Uploads + +Uploads are dynamic files stored per-record. + +**Table Definition:** +```yaml +name: product +properties: + - name: image + type: upload +``` + +**Form:** +```liquid +{% form %} + +{% endform %} +``` + +**Displaying Uploads:** +```liquid +{% graphql product = 'get_product', id: id %} +{{ product.record.properties.image.file_name }} +``` + +**Upload Properties:** + +| Property | Description | +|----------|-------------| +| `url` | Direct file URL | +| `file_name` | Original filename | +| `content_type` | MIME type | +| `size` | File size in bytes | + +### Assets vs Uploads + +| Aspect | Assets | Uploads | +|--------|--------|---------| +| Location | `app/assets/` | Record properties | +| Use Case | Static files (CSS, JS, logos) | Dynamic content | +| Quantity | Thousands expected | Millions supported | +| CDN | Yes | Yes | +| Max Size | 2GB | 2GB | + +### Direct S3 Upload + +platformOS uses **direct S3 upload** - files go straight to AWS S3 without passing through the application server. + +**Advantages:** +- **Speed** - No middleman, faster uploads +- **Cost** - Less bandwidth and server load +- **Security** - No file processing on app server +- **Scalability** - Handle unlimited concurrent uploads +- **Size** - Up to 5GB single file, 5TB multipart + +**Upload Flow:** +``` +1. User selects file +2. Browser requests signed S3 URL from platformOS +3. Browser uploads directly to S3 +4. S3 returns success +5. platformOS saves file reference to record +``` + +### Upload Configuration Options + +**Table Definition with Options:** +```yaml +name: product +properties: + - name: image + type: upload + options: + public: true # Public or private access + max_size: 5242880 # 5MB in bytes + versions: + - name: thumbnail + resize: '200x200>' # Resize to fit 200x200 + - name: medium + resize: '800x600>' + extensions: + - jpg + - png + - gif +``` + +### Upload Versions + +Automatically generate resized versions: + +```yaml +properties: + - name: photo + type: upload + options: + versions: + - name: thumb + resize: '100x100#' # Exact fit, may crop + - name: medium + resize: '300x300>' # Fit within, no upscale + - name: large + resize: '800x800>' +``` + +**Access versions in Liquid:** +```liquid +{{ product.properties.photo.url }} # Original +{{ product.properties.photo.versions.thumb.url }} # Thumbnail +{{ product.properties.photo.versions.medium.url }} # Medium +``` + +### Image Processing Options + +| Option | Description | Example | +|--------|-------------|---------| +| `resize: '100x100'` | Resize to dimensions | Fit within | +| `resize: '100x100>'` | Resize only if larger | Downscale only | +| `resize: '100x100<'` | Resize only if smaller | Upscale only | +| `resize: '100x100#'` | Exact dimensions | May crop | +| `resize: '100x100^'` | Minimum dimensions | May crop | + +--- + +## 16. Best Practices + +### Code Organization + +``` +app/ +├── views/ +│ ├── pages/ # Route handlers +│ ├── layouts/ # Page wrappers +│ └── partials/ +│ ├── components/ # UI components +│ ├── forms/ # Form partials +│ └── helpers/ # Utility partials +├── forms/ # Form configurations +├── graphql/ # Data queries +│ ├── records/ +│ ├── users/ +│ └── system/ +└── schema/ # Table definitions +``` + +### Naming Conventions + +| Component | Convention | Example | +|-----------|------------|---------| +| Tables | snake_case | `blog_post` | +| Properties | snake_case | `published_at` | +| Pages | snake_case | `about_us.liquid` | +| Partials | snake_case | `header.liquid` | +| Forms | snake_case | `contact_form.liquid` | +| GraphQL | snake_case | `get_blog_posts.graphql` | + +### Security Best Practices + +1. **Always use authorization policies** for protected routes +2. **Validate all inputs** using form validations +3. **Escape output** using Liquid's auto-escaping +4. **Use HTTPS** for all production instances +5. **Store secrets** in Partner Portal constants, not code +6. **Sanitize user content** before displaying + +### Performance Best Practices + +1. **Use pagination** for all list queries +2. **Load related records** in single GraphQL query +3. **Use background jobs** for long operations +4. **Cache expensive queries** using static cache +5. **Optimize images** before uploading as assets +6. **Minimize GraphQL response size** with specific field selection + +### Error Handling + +```liquid +{% graphql result = 'create_record', name: name %} + +{% if result.record_create.errors %} +
+ {% for error in result.record_create.errors %} +

{{ error.message }}

+ {% endfor %} +
+{% else %} +

Success! ID: {{ result.record_create.id }}

+{% endif %} +``` + +--- + +## 17. Common Gotchas & Pitfalls + +### 1. Variable Scope in Background Jobs + +**WRONG:** +```liquid +{% assign user_id = context.current_user.id %} +{% background %} + {{ user_id }} {# nil - not passed #} +{% endbackground %} +``` + +**CORRECT:** +```liquid +{% assign user_id = context.current_user.id %} +{% background user_id: user_id %} + {{ user_id }} {# Works! #} +{% endbackground %} +``` + +### 2. N+1 Query Problem + +**WRONG (N+1 queries):** +```liquid +{% graphql companies = 'get_companies' %} +{% for company in companies.records.results %} + {% graphql programmers = 'get_programmers', company_id: company.id %} + {# Each iteration = 1 query! #} +{% endfor %} +``` + +**CORRECT (single query):** +```graphql +query get_companies_with_programmers { + records( + filter: { table: { value: "company" } } + ) { + results { + id + properties + programmers: related_records( + table: "programmer" + foreign_property: "company_id" + ) { + id + properties + } + } + } +} +``` + +### 3. Form Field Name Format + +**WRONG:** +```liquid + {# Won't bind to form #} +``` + +**CORRECT:** +```liquid + +``` + +### 4. Module File References + +**WRONG:** +```liquid +{% render 'modules/my_module/public/header' %} +``` + +**CORRECT:** +```liquid +{% render 'modules/my_module/header' %} +``` + +### 5. Date/Time Formatting + +**WRONG:** +```liquid +{{ '2024-01-01' | strftime: '%Y' }} {# Error - not a time object #} +``` + +**CORRECT:** +```liquid +{{ '2024-01-01' | to_time | strftime: '%Y' }} +``` + +### 6. Array vs JSONB Confusion + +**Arrays** - for simple lists: +```yaml +type: array +# Value: ["a", "b", "c"] +``` + +**JSONB** - for complex objects: +```yaml +type: jsonb +# Value: {"nested": {"key": "value"}} +``` + +### 7. Form Resource Owner + +**For public forms** (contact, newsletter): +```yaml +resource_owner: anyone +``` + +**For authenticated forms** (profile edit): +```yaml +resource_owner: self +``` + +**For admin forms**: +```yaml +resource_owner: anyone_with_token +authorization_policies: + - admin_only_policy +``` + +### 8. Whitespace in Liquid + +**Problem:** Extra whitespace in output +```liquid +{% if true %} + Content +{% endif %} +{# Outputs newlines around content #} +``` + +**Solution:** Use whitespace control +```liquid +{%- if true -%} + Content +{%- endif -%} +``` + +### 9. GraphQL Variable Types + +**Integer vs Float:** +```graphql +# Integer property +{ name: "count", value_int: 5 } + +# Float property +{ name: "price", value_float: 19.99 } +``` + +**Boolean:** +```graphql +{ name: "active", value_boolean: true } +``` + +### 10. Soft Delete vs Hard Delete + +**Soft delete** (default): +```graphql +mutation { + record_delete(id: "123") { + id + deleted_at # Timestamp set + } +} +``` + +**Hard delete** (permanent): +```graphql +mutation { + record_delete(id: "123", hard_delete: true) { + id + } +} +``` + +### 11. Reserved Names + +Avoid these reserved names for custom tables and properties: + +**System Fields (automatically created):** +- `id` - Record UUID +- `created_at` - Creation timestamp +- `updated_at` - Last update timestamp +- `deleted_at` - Soft delete timestamp +- `type_name` - Table name +- `properties` - Property container + +**Reserved Words:** +- `user`, `users` - Built-in User table +- `session`, `sessions` - Session management +- `record`, `records` - Record operations +- `constant`, `constants` - System constants +- `table`, `tables` - Table metadata + +### 12. Form Resource Owner Confusion + +| Value | When to Use | +|-------|-------------| +| `anyone` | Public forms (contact, newsletter) | +| `self` | User editing their own data | +| `anyone_with_token` | API endpoints with token auth | + +**Wrong:** +```yaml +resource_owner: self # Won't work for public contact form +``` + +**Correct:** +```yaml +resource_owner: anyone # For public forms +``` + +### 13. Module File Deletion Behavior + +By default, module files are **NOT deleted** during deploy to protect private files. + +To enable deletion for a module: +```yaml +# app/config.yml +modules_that_allow_delete_on_deploy: + - my_module +``` + +### 14. GraphQL Query Caching + +GraphQL queries are cached by default. To bypass cache: +```graphql +query { + records( + per_page: 10 + filter: { table: { value: "product" } } + ) @skip_cache { + results { id } + } +} +``` + +### 15. File Upload Size Limits + +| Upload Type | Max Size | +|-------------|----------| +| Direct S3 (single part) | 5 GB | +| Direct S3 (multipart) | 5 TB | +| Application-processed | 2 GB | + +### 16. Background Job Payload Limits + +```liquid +{# WRONG - payload too large #} +{% background data: huge_array_with_thousands_of_items %} + +{# CORRECT - pass reference only #} +{% background record_id: record_id %} + {% graphql record = 'get_record', id: record_id %} + {# Process data in background #} +{% endbackground %} +``` + +### 17. Liquid Truthiness + +In Liquid, only `nil` and `false` are falsy. Empty strings and zero are truthy: + +```liquid +{% if '' %}TRUE{% endif %} {# TRUE! #} +{% if 0 %}TRUE{% endif %} {# TRUE! #} +{% if empty_array %}TRUE{% endif %} {# FALSE (nil) #} +{% if false %}TRUE{% endif %} {# FALSE #} +``` + +Use `blank` and `present` for better checks: +```liquid +{% if '' == blank %}EMPTY{% endif %} {# EMPTY #} +{% if 0 == blank %}ZERO IS BLANK{% endif %} {# Not blank! #} +``` + +--- + +## 18. Performance Optimization + +### Measuring Performance + +**time_diff filter:** +```liquid +{% assign start = 'now' | to_time %} + +{% graphql posts = 'get_posts' %} + +{% assign duration = start | time_diff: 'now' %} +

Query took: {{ duration }}ms

+``` + +### Query Optimization + +**1. Select only needed fields:** +```graphql +# BAD - fetches everything +query { + records { results { properties } } +} + +# GOOD - specific fields +query { + records { + results { + id + properties + } + } +} +``` + +**2. Use pagination:** +```graphql +query { + records(per_page: 20, page: 1) { + total_entries + results { id } + } +} +``` + +**3. Load related records efficiently:** +```graphql +query { + records(filter: { table: { value: "order" } }) { + results { + id + items: related_records(table: "order_item") { + id + properties + } + } + } +} +``` + +### Caching Strategies + +**Static Cache (Edge Caching):** +```liquid +--- +slug: public-page +response_headers: + Cache-Control: public, max-age=3600 +--- +``` + +**Fragment Caching:** +```liquid +{% cache key: 'sidebar', expire: 3600 %} + {% graphql categories = 'get_categories' %} + {% for category in categories.records.results %} + {{ category.properties.name }} + {% endfor %} +{% endcache %} +``` + +### Background Job Optimization + +**Keep payloads small:** +```liquid +{# BAD - large payload #} +{% background data: huge_array %} + +{# GOOD - pass reference #} +{% assign job_id = 'process_' | append: record_id %} +{% background job_id: job_id, record_id: record_id %} + {% graphql record = 'get_record', id: record_id %} + {# Process in background #} +{% endbackground %} +``` + +--- + +## 19. Testing & CI/CD + +### pos-cli GUI + +```bash +# Start GUI for GraphQL development +pos-cli gui serve staging + +# Access at http://localhost:3333 +``` + +### platformOS Check + +```bash +# Install +npm install -g @platformos/platformos-check + +# Run checks +platformos-check + +# Auto-fix issues +platformos-check --auto-correct +``` + +### GitHub Actions CI + +**File:** `.github/workflows/platformos.yml` +```yaml +name: platformOS CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install pos-cli + run: npm install -g @platformos/pos-cli + + - name: Deploy to Staging + run: pos-cli deploy staging + env: + MPKIT_TOKEN: ${{ secrets.MPKIT_TOKEN }} + MPKIT_URL: ${{ secrets.STAGING_URL }} + + - name: Run Tests + run: npm test +``` + +### Release Pool Setup + +1. Create dedicated test instances in Partner Portal +2. Configure GitHub secrets: + - `MPKIT_TOKEN` + - `STAGING_URL` + - `PRODUCTION_URL` + +### Testing Best Practices + +1. **Unit test** GraphQL queries +2. **Integration test** form submissions +3. **E2E test** critical user flows +4. **Performance test** with realistic data volumes +5. **Security test** authorization policies + +--- + +## 20. System Limitations + +### Resource Limits + +| Resource | Limit | Notes | +|----------|-------|-------| +| File upload size | 2GB | Assets and uploads | +| Background job payload | 100KB | Keep payloads small | +| Background job execution | 1-60 min | Depends on priority | +| GraphQL query complexity | Varies | Monitor performance | +| Records per query | Unlimited | Use pagination | +| Assets | Thousands | Use uploads for dynamic content | +| Uploads | Millions | No practical limit | + +### Background Job Limits + +| Priority | Max Execution | Use For | +|----------|---------------|---------| +| `high` | 1 minute | Critical, urgent tasks | +| `default` | 5 minutes | Standard operations | +| `low` | 60 minutes | Heavy processing | + +### Rate Limiting + +- API calls may be rate-limited based on plan +- Background job scheduling has queue limits +- GraphQL queries have complexity scoring + +### Reserved Names + +Avoid these names for custom tables/properties: +- `id`, `created_at`, `updated_at`, `deleted_at` +- `type_name`, `properties`, `user` +- Built-in Liquid objects and filters + +--- + +## 22. Data Import/Export + +### Exporting Data + +```bash +# Export all data from an instance +pos-cli data export staging --path=./export.json + +# Export specific tables +pos-cli data export staging --tables=products,orders --path=./products.json +``` + +### Importing Data + +```bash +# Import data to an instance +pos-cli data import staging ./export.json + +# Import with transformations +pos-cli data import staging ./data.json --transform=./transform.js +``` + +### Data Export Format + +```json +{ + "users": [ + { + "id": "123", + "email": "user@example.com", + "created_at": "2024-01-15T10:00:00Z", + "properties": { + "first_name": "John", + "last_name": "Doe" + } + } + ], + "records": { + "product": [ + { + "id": "456", + "properties": { + "name": "Widget", + "price": 19.99 + } + } + ] + } +} +``` + +### Programmatic Import with Migrations + +```liquid +{# app/migrations/20240115000000_import_products.liquid #} +{% parse_json data %} + {{ 'data/products.json' | load_file }} +{% endparse_json %} + +{% for product in data.products %} + {% graphql result = 'create_product', + name: product.name, + price: product.price, + sku: product.sku + %} + {% log result %} +{% endfor %} +``` + +### Cleaning Instance Data ```bash -pos-cli migrations generate dev init_staging_constants -# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid +# WARNING: This deletes all data! +pos-cli data clean staging + +# Clean specific tables +pos-cli data clean staging --tables=products,orders ``` -### Example: Initialize Staging Constants +--- + +## 23. Quick Reference + +### File Templates +**New Page:** ```liquid -{% liquid - if context.environment == 'staging' - graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123' - graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com' - endif -%} +--- +slug: my-page +layout: application +--- + +

Page Title

``` -### Example: Seed Data +**New Table:** +```yaml +name: my_table +properties: + - name: name + type: string +``` +**New Form:** ```liquid -{% parse_json categories %} -["Electronics", "Clothing", "Books"] -{% endparse_json %} +--- +name: my_form +resource: my_table +resource_owner: anyone +redirect_to: /success +fields: + properties: + name: + validation: + presence: true +--- + +{% form %} + + +{% endform %} +``` -{% for category in categories %} - {% graphql _ = 'categories/create', name: category %} +**New GraphQL Query:** +```graphql +query my_query($param: String) { + records(filter: { table: { value: "my_table" } }) { + results { id properties } + } +} +``` + +### Common Liquid Patterns + +**Conditional rendering:** +```liquid +{% if condition %} + +{% elsif other_condition %} + +{% else %} + +{% endif %} +``` + +**Loop with index:** +```liquid +{% for item in items %} + {{ forloop.index }}: {{ item.name }} {% endfor %} ``` -### Running Migrations +**Pagination:** +```liquid +{% if records.has_previous_page %} + Previous +{% endif %} + +{% if records.has_next_page %} + Next +{% endif %} +``` + +### Common GraphQL Patterns + +**Create with error handling:** +```graphql +mutation { + record_create(record: { table: "post", properties: [] }) { + id + errors { message } + } +} +``` + +**Update specific fields:** +```graphql +mutation { + record_update(id: "123", record: { properties: [{ name: "status", value: "published" }] }) { + id + properties + } +} +``` + +**Search with filters:** +```graphql +query { + records( + filter: { + table: { value: "product" } + properties: [{ name: "category", value: "electronics" }] + created_at: { gte: "2024-01-01" } + } + ) { + results { id } + } +} +``` + +### pos-cli Commands + +```bash +# Authentication +pos-cli auth login # Login to Partner Portal + +# Development +pos-cli sync staging # Watch and sync changes +pos-cli deploy staging # Deploy to instance +pos-cli deploy staging -f # Force deploy (delete missing files) + +# Data +pos-cli data export staging # Export instance data +pos-cli data import staging file.json # Import data +pos-cli migrations run staging # Run pending migrations + +# Modules +pos-cli modules install module_name # Install module +pos-cli modules remove module_name # Remove module + +# GUI +pos-cli gui serve staging # Start development GUI + +# Logs +pos-cli logs staging # Stream logs +``` + +### Error Messages Reference + +| Error | Cause | Solution | +|-------|-------|----------| +| `Record not found` | Invalid ID | Check record exists | +| `Validation failed` | Invalid data | Check form validations | +| `Unauthorized` | Policy failed | Check authorization | +| `Rate limited` | Too many requests | Add delays, use caching | +| `Timeout` | Query too slow | Optimize query, add pagination | +| `Property not found` | Wrong property name | Check table schema | +| `Table not found` | Wrong table name | Check table definition | +| `Form not found` | Wrong form name | Check form file exists | + +### GraphQL Property Type Mapping + +| Property Type | GraphQL Input | Example | +|---------------|---------------|---------| +| `string` | `value: "text"` | `{ name: "title", value: "Hello" }` | +| `integer` | `value_int: 42` | `{ name: "count", value_int: 5 }` | +| `float` | `value_float: 19.99` | `{ name: "price", value_float: 19.99 }` | +| `boolean` | `value_boolean: true` | `{ name: "active", value_boolean: true }` | +| `date` | `value: "2024-01-15"` | `{ name: "birthday", value: "2024-01-15" }` | +| `datetime` | `value: "2024-01-15T10:00:00Z"` | ISO 8601 format | +| `array` | `value_array: ["a", "b"]` | `{ name: "tags", value_array: ["a", "b"] }` | +| `jsonb` | `value_json: "{}"` | JSON string | +| `upload` | Via form only | File uploads | + +### Form Validation Reference + +| Validation | Syntax | Description | +|------------|--------|-------------| +| `presence` | `presence: true` | Required field | +| `email` | `email: true` | Valid email format | +| `uniqueness` | `uniqueness: true` | Must be unique | +| `length` | `length: { minimum: 5, maximum: 100 }` | String length | +| `numericality` | `numericality: { greater_than: 0 }` | Number range | +| `confirmation` | `confirmation: true` | Must match confirmation field | +| `url` | `url: true` | Valid URL format | + +### pos-cli Extended Commands + +```bash +# Authentication +pos-cli auth login # Login to Partner Portal +pos-cli auth logout # Logout + +# Development +pos-cli sync staging # Watch and sync changes +pos-cli sync staging --live-reload # With live reload +pos-cli deploy staging # Deploy to instance +pos-cli deploy staging -f # Force deploy (delete missing files) +pos-cli deploy staging --direct-assets # Deploy assets directly + +# Data Management +pos-cli data export staging # Export all data +pos-cli data export staging --tables=products,orders +pos-cli data import staging file.json # Import data +pos-cli data clean staging # Delete all data (DANGER!) +pos-cli migrations run staging # Run pending migrations +pos-cli migrations status staging # Check migration status + +# Modules +pos-cli modules install module_name # Install module +pos-cli modules install module_name@1.2 # Specific version +pos-cli modules remove module_name # Remove module +pos-cli modules list staging # List installed modules + +# GUI Tools +pos-cli gui serve staging # Start development GUI +pos-cli gui serve staging --port 3333 # Custom port -- **Automatic:** Pending migrations run on `pos-cli deploy` -- **Manual:** `pos-cli migrations run TIMESTAMP dev` +# Logs +pos-cli logs staging # Stream logs +pos-cli logs staging --tail 100 # Last 100 lines +pos-cli logs staging --follow # Follow new logs -### Migration States +# Environment +pos-cli env list # List environments +pos-cli env add production # Add environment +pos-cli env remove staging # Remove environment -- **pending** — not yet executed (runs on next deploy) -- **done** — successfully completed (will not run again) -- **error** — failed (can edit and retry) +# Testing +pos-cli test staging # Run tests -For large data imports, use Data Import/Export instead of migrations. +# Debug +pos-cli shell staging # Interactive shell +``` --- -## 21. Testing +## 24. Translations + +### Overview + +Translations serve three main purposes: +1. **Multi-language sites** - Static copy in multiple languages +2. **Date formatting** - Consistent date/time display +3. **Flash messages** - System message localization + +### Translation Files + +**File:** `app/translations/en.yml` +```yaml +en: + hello: "Hello" + welcome: "Welcome to our site" + buttons: + submit: "Submit" + cancel: "Cancel" + errors: + not_found: "Page not found" +``` + +**File:** `app/translations/es.yml` +```yaml +es: + hello: "Hola" + welcome: "Bienvenido a nuestro sitio" + buttons: + submit: "Enviar" + cancel: "Cancelar" + errors: + not_found: "Página no encontrada" +``` + +### Using Translations in Liquid + +**Basic translation:** +```liquid +{{ 'hello' | t }} # Output: Hello (or Hola) +``` + +**Nested keys:** +```liquid +{{ 'buttons.submit' | t }} # Output: Submit +{{ 'errors.not_found' | t }} # Output: Page not found +``` + +**With interpolation:** +```yaml +# en.yml +welcome_user: "Welcome, {{ name }}!" +``` +```liquid +{{ 'welcome_user' | t: name: user.first_name }} +``` -Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. +### Date Localization -Every new feature MUST have unit tests for commands. +Use the `l` (localize) filter for consistent date formatting: +```yaml +# en.yml +date: + formats: + short: "%b %d, %Y" + long: "%B %d, %Y %H:%M" +``` ```liquid -{% function result = 'commands/products/create', title: "Test" %} -{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %} -{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %} -{% return contract %} +{{ 'now' | l: 'short' }} # Jan 15, 2024 +{{ post.published_at | l: 'long' }} # January 15, 2024 14:30 ``` -Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. +### Language Detection + +platformOS automatically detects language from: +1. User's `language` property (if set) +2. Browser's Accept-Language header +3. Default language (English) + +Access current language: +```liquid +{{ context.language }} # Current language code (e.g., "en") +``` --- -## 22. CLI Commands +## 25. Activity Feeds -```bash -# Deployment -pos-cli deploy dev +### Overview -# Sync (MUST sync every file after modification) -pos-cli sync dev +Activity Feeds implement the [W3C Activity Streams 2.0](https://www.w3.org/TR/2017/REC-activitystreams-core-20170523/) specification for tracking user activities. -# Logs -pos-cli logs dev +**Key Characteristics:** +- Activities are **immutable** (append-only) +- Each activity has a **unique UUID** +- Activities can be shared between actors +- Activities represent events that happened in the past -# Linting (MUST run after EVERY file change) -platformos-check +### Activity Structure -# Run Liquid inline -pos-cli exec liquid dev '' +```json +{ + "actor": { + "type": "Person", + "id": "User.1", + "name": "Sally Smith" + }, + "type": "Create", + "object": { + "type": "Relationship", + "id": "Relationship.42" + }, + "target": { + "type": "Group", + "id": "Group.5" + } +} +``` -# Run GraphQL inline -pos-cli exec graphql dev '' +### Creating Activities + +**GraphQL Mutation:** +```graphql +mutation create_activity { + activity_create( + activity: { + type: "Join" + actor: { + type: "Person" + id: "User.123" + name: "John Doe" + } + object: { + type: "Group" + id: "Group.456" + } + } + ) { + id + uuid + } +} +``` -# Tests -pos-cli test run staging +### Publishing to Feeds -# Modules -pos-cli modules install -pos-cli modules download +After creating an activity, publish it to feeds: -# Constants -pos-cli constants set --name KEY --value "value" dev +```graphql +mutation publish_to_feed { + feed_publish( + feed_id: "user_123_notifications" + activity_uuid: "abc-123-uuid" + ) { + id + } +} +``` -# Generate CRUD -pos-cli generate run modules/core/generators/crud --include-views +### Querying Feeds -# Migrations -pos-cli migrations generate dev -pos-cli migrations run TIMESTAMP dev +```graphql +query get_user_feed { + feeds( + feed_id: "user_123_notifications" + per_page: 20 + ) { + total_entries + results { + id + uuid + type + actor + object + target + created_at + } + } +} ``` +### Common Activity Types + +| Type | Description | +|------|-------------| +| `Create` | Created something | +| `Update` | Updated something | +| `Delete` | Deleted something | +| `Join` | Joined a group/event | +| `Leave` | Left a group/event | +| `Follow` | Started following | +| `Like` | Liked content | +| `Comment` | Commented on content | +| `Share` | Shared content | +| `Approve` | Approved a request | + --- -## 23. Modules Reference +## 26. JSON Documents + +### Overview + +JSON Documents provide a schemaless data storage option for flexible, document-based data. Unlike Records (which require a Table schema), JSON Documents can store any valid JSON structure. + +**Use Cases:** +- Configuration data +- Unstructured content +- Temporary data storage +- Data that doesn't fit a rigid schema + +### Creating JSON Documents + +**GraphQL Mutation:** +```graphql +mutation create_json_document { + json_document_create( + document: { + name: "site_config" + content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}" + } + ) { + id + name + content + created_at + } +} +``` + +### Querying JSON Documents + +```graphql +query get_json_document { + json_document(name: "site_config") { + id + name + content + created_at + updated_at + } +} + +query list_json_documents { + json_documents( + per_page: 10 + sort: [{ created_at: { order: DESC } }] + ) { + results { + id + name + content + } + } +} +``` + +### Updating JSON Documents + +```graphql +mutation update_json_document { + json_document_update( + name: "site_config" + document: { + content: "{\"theme\": \"light\", \"features\": [\"blog\", \"shop\", \"forum\"]}" + } + ) { + id + content + updated_at + } +} +``` + +### Using in Liquid + +```liquid +{% graphql config = 'get_json_document', name: 'site_config' %} +{% assign settings = config.json_document.content | parse_json %} + +Theme: {{ settings.theme }} +Features: {{ settings.features | join: ', ' }} +``` + +### JSON Document vs Records -| Module | Install | Purpose | Required | -|--------|---------|---------|----------| -| `core` | Required | Commands, events, validators | YES | -| `user` | Required | Auth, RBAC, OAuth2 | YES | -| `common-styling` | Required | CSS, components | YES | -| `tests` | Optional | Testing framework | YES (for testing) | -| `payments` + `payments_stripe` | Optional | Stripe payments | No | -| `chat` | Optional | WebSocket messaging | No | -| `openai` | Optional | OpenAI integration | No | +| Feature | JSON Documents | Records | +|---------|---------------|---------| +| Schema | Schemaless | Defined in Table YAML | +| Validation | None | Form validation | +| Structure | Any JSON | Fixed properties | +| Use Case | Config, flexible data | Structured entities | +| GraphQL | `json_document_*` | `record_*` | --- -## 24. Forbidden Behaviors +## 27. AI Embeddings + +### Overview + +platformOS supports AI embeddings for semantic search and similarity matching. Embeddings are vector representations of text that capture semantic meaning. + +**Use Cases:** +- Semantic search +- Content recommendation +- Similarity matching +- Clustering + +### Creating Embeddings + +**GraphQL Mutation:** +```graphql +mutation create_embedding { + embedding_create( + embedding: { + name: "product_description" + value: "High-quality wireless headphones with noise cancellation" + target_id: "product_123" + target_type: "Product" + } + ) { + id + vector + } +} +``` + +### Semantic Search + +```graphql +query semantic_search { + embeddings_search( + query: "wireless audio devices" + limit: 10 + threshold: 0.7 + ) { + results { + id + target_id + target_type + similarity + value + } + } +} +``` + +### Querying Embeddings -You MUST NOT: -- Edit files in `./modules/` (read-only) -- Break long lines in `{% liquid %}` blocks (causes syntax errors) -- Invent Liquid tags, filters, or GraphQL types that do not exist -- Use `{% form %}` tag (use HTML `
` only) -- Bypass security (CSRF tokens, authorization) -- Access databases directly outside GraphQL -- Deploy without running `platformos-check` -- Sync files outside `./app/` -- Use `authorization_policies/` directly (use pos-module-user) -- Use `context.current_user` directly (use user module queries) -- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling) -- Hardcode API keys, secrets, or environment-specific URLs -- Hardcode user-facing text in partials (use translations) -- Put HTML, JS, or CSS in page files -- Call GraphQL from partials -- Put raw GraphQL in pages (use `.graphql` files) -- Create or modify application files outside the `app/` directory +```graphql +query get_embedding { + embedding( + target_id: "product_123" + target_type: "Product" + ) { + id + name + value + vector + created_at + } +} +``` + +### Deleting Embeddings + +```graphql +mutation delete_embedding { + embedding_delete( + target_id: "product_123" + target_type: "Product" + ) { + id + } +} +``` + +### Embedding Parameters + +| Parameter | Description | +|-----------|-------------| +| `name` | Identifier for the embedding type | +| `value` | The text to embed | +| `target_id` | ID of the associated entity | +| `target_type` | Type of the associated entity | +| `vector` | The computed embedding vector (read-only) | --- -## 25. Pre-Flight Checklist +## 28. Migrations + +### Overview -Before every change, verify: +Migrations are Liquid scripts that run once to transform data. They are useful for: +- Data transformations during schema changes +- Bulk data updates +- One-time data imports -- [ ] No underscore prefix in partial filenames -- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid` -- [ ] Pages have ONE HTTP method each -- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files) -- [ ] No HTML/JS/CSS in pages -- [ ] No hardcoded text in partials (use translations) -- [ ] `platformos-check` passes with 0 errors -- [ ] Every file synced after modification -- [ ] All list queries support pagination (`per_page`, `page`) -- [ ] All inputs validated in commands before persisting -- [ ] CSS/JS minified, `asset_url` used for cache busting +### Creating Migrations -### Asset URL Usage +**File:** `app/migrations/20240115120000_add_status_to_products.liquid` +```liquid +{% graphql products = 'get_all_products' %} + +{% for product in products.records.results %} + {% graphql result = 'update_product_status', + id: product.id, + status: 'active' + %} + {% log result %} +{% endfor %} +``` + +### Migration File Naming + +Migrations are executed in alphabetical order. Use timestamps as prefixes: +``` +app/migrations/ +├── 20240101000000_initial_setup.liquid +├── 20240115120000_add_status.liquid +└── 20240201000000_migrate_images.liquid +``` + +### Running Migrations + +```bash +# Run pending migrations +pos-cli migrations run staging + +# Check migration status +pos-cli migrations status staging +``` +### Migration Best Practices + +1. **Make migrations idempotent** - Running twice should not cause errors: +```liquid +{% graphql product = 'get_product', id: product_id %} +{% unless product.record.properties.status %} + {# Only update if status is not set #} + {% graphql result = 'update_product', id: product_id, status: 'active' %} +{% endunless %} +``` + +2. **Use background jobs for large migrations:** ```liquid -{{ 'images/img.png' | asset_url }} +{% background source_name: 'data_migration' %} + {% graphql records = 'get_all_records' %} + {% for record in records.records.results %} + {# Process each record #} + {% endfor %} +{% endbackground %} ``` + +3. **Test migrations on staging first** +4. **Log progress for debugging:** +```liquid +{% log 'Migration started' %} +{% log 'Processed ' | append: count | append: ' records' %} +``` + +### Migration Limitations + +- Migrations run as background jobs +- Should complete within a few minutes +- For long-running operations, use low-priority background jobs +- Failed migrations can be retried + +--- + +## Resources + +- **Documentation:** https://documentation.platformos.com/ +- **API Reference:** https://documentation.platformos.com/api-reference +- **Examples:** https://examples.platform-os.com/ +- **GitHub:** https://github.com/Platform-OS +- **Partner Portal:** https://partners.platformos.com/ +- **Community:** https://community.platformos.com/ + +--- + +*This guide is designed for LLM agents developing on platformOS. For the most up-to-date information, always refer to the official documentation.* diff --git a/src/data/resources/short-platformos-development-guide.md b/src/data/resources/short-platformos-development-guide.md new file mode 100644 index 0000000..ec2b2df --- /dev/null +++ b/src/data/resources/short-platformos-development-guide.md @@ -0,0 +1,1006 @@ +# platformOS Development Guide + +Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory +workflow — read it before touching any file. + +## 0. MANDATORY WORKFLOW — Read Before Writing Any Code + +You MUST follow this loop for every feature. Each step produces structured output +the next step consumes — skipping any step produces invalid state that downstream +tools will reject. + +1. **`project_map`** — understand what already exists. MUST be called once per session + before any scaffold or write. +2. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files. + Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains + rules that are NOT in your training data and that differ from Shopify, Rails, and + generic Liquid. +3. **`scaffold(type, name, properties, write: true)`** — generate AND write the + authoritative file set from platformOS-native templates. MUST use scaffold whenever + a file set matches one of its types (crud, api, command, query, partial, page). + Scaffold output is pre-validated — no `validate_intent` or `validate_code` needed + on untouched scaffold files. `validate_intent({ scaffold_output })` is OPTIONAL + (review only, for a dry-run preview before committing). +4. **Hand-drafted files** — for files not covered by scaffold, call + `validate_intent({ intent })` (REQUIRED) then `validate_code` per file before + writing. `validate_intent` writes `pending_files`, `pending_translations`, + `pending_pages` into session state that `validate_code` and `analyze_project` + automatically merge — you do NOT need to pass them on every call. +5. **Feedback loop.** When `validate_code` returns `status !== "ok"` or + `must_fix_before_write: true`, fix every error and re-validate. MUST NOT write + a hand-drafted file to disk until validation passes. + +### MUST-CALL domains (by feature type) + +- **Auth code** — `domain_guide(domain: "authentication")` +- **Any form** — `domain_guide(domain: "forms")` +- **New pages** — `domain_guide(domain: "pages")` +- **New partials** — `domain_guide(domain: "partials")` +- **GraphQL ops** — `domain_guide(domain: "graphql")` +- **Any new domain** — `domain_guide(domain: "", section: "gotchas")` + +### MUST NOT + +- Use `{% include %}` for app code — deprecated. Use `{% render %}` or + `{% function %}`. +- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These + do not exist in platformOS. +- Write hand-drafted files to disk without calling `validate_code` on the proposed + content first. (Scaffold-written files are exempt — they are pre-validated.) +- Assume module call syntax from memory — call `module_info(name)` to get the + authoritative live-scan API surface. +- Ignore `consult_before_writing` in a scaffold response. Every domain listed there + MUST be consulted via `domain_guide` before writing. + +### Session-start checklist + +Before your first tool call, the following are true: + +- [ ] `server_status` called — confirms LSP and indexes are ready, lists + `domain_guides` and `session_pending`. +- [ ] `load_development_guide` called (this document) — re-read if you lose + context or are unsure which step comes next. +- [ ] `project_map` called once for full project baseline. + +Proceed only when all three are checked. + +## 1. Technology Stack + +platformOS uses three primary technologies: +- **Liquid** — server-side templating language +- **GraphQL** — data operations (built-in queries/mutations only) +- **YAML** — configuration for schemas, translations, and settings + +The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access. + +platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag. + +### Source of Truth + +The official platformOS documentation is the ONLY source of truth: + +| Resource | URL | +|----------|-----| +| Official Docs | documentation.platformos.com | +| GraphQL Schema | documentation.platformos.com/api/graphql/schema | +| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md | +| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md | +| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md | +| Core Module | github.com/Platform-OS/pos-module-core (README) | +| User Module | github.com/Platform-OS/pos-module-user (README) | +| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) | +| Payments Module | github.com/Platform-OS/pos-module-payments (README) | +| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) | +| Tests Module | github.com/Platform-OS/pos-module-tests (README) | +| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md | + +You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation. + +--- + +## 2. Directory Structure + +``` +project-root/ +├── app/ +│ ├── assets/ # Static files (images, fonts, styles, scripts) +│ ├── views/ +│ │ ├── pages/ # Controllers — NO HTML here +│ │ ├── layouts/ # Wrapper templates +│ │ └── partials/ # Reusable template snippets +│ ├── lib/ +│ │ ├── commands/ # Business logic (build → check → execute) +│ │ ├── queries/ # Data retrieval wrappers +│ │ ├── events/ # Event definitions +│ │ └── consumers/ # Event handlers +│ ├── schema/ # Database table definitions (YAML) +│ ├── graphql/ # GraphQL query/mutation files +│ ├── emails/ # Email templates +│ ├── smses/ # SMS templates +│ ├── api_calls/ # Third-party API integrations +│ ├── translations/ # i18n content (YAML) +│ ├── authorization_policies/ # DO NOT USE — use pos-module-user +│ ├── migrations/ # One-time migration scripts +│ └── config.yml # Feature flags +├── modules/ # Downloaded/custom modules (READ-ONLY) +└── .pos # Environment endpoints +``` + +All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`. + +The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only. + +### File Naming Conventions + +| Directory | Pattern | Example | +|-----------|---------|---------| +| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` | +| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` | +| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` | +| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` | +| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` | +| Assets | `app/assets//` | `app/assets/images/logo.png` | +| Translations | `app/translations/.yml` | `app/translations/en.yml` | + +### File Formats + +| Extension | Content-Type | URL | +|-----------|--------------|-----| +| `*.liquid` or `*.html.liquid` | `text/html` | `/path` | +| `*.json.liquid` | `application/json` | `/path.json` | +| `*.js.liquid` | `application/javascript` | `/path.js` | + +--- + +## 3. Architecture Rules + +### Pages MUST Be Controllers + +Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method. + +### Business Logic MUST Live in Commands + +All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build → check → execute pattern. + +### Path Resolution + +- `{% render 'blog_posts/card' %}` → `app/views/partials/blog_posts/card.liquid` +- `{% function r = 'commands/blog_posts/create' %}` → `app/lib/commands/blog_posts/create.liquid` +- `{% function r = 'queries/blog_posts/search' %}` → `app/lib/queries/blog_posts/search.liquid` + +The `lib/` prefix is implicit in `function` calls — do NOT include it. + +### Separation of Concerns + +- UI (Liquid templates) MUST be in partials and layouts +- Data operations (GraphQL) MUST be in query/mutation files +- Logic (commands) MUST be in `app/lib/commands/` + +### Modules First + +Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic. + +### Generators First (DEPRECATED — DO NOT USE) + +You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available. + +--- + +## 4. Pages + +Pages are controllers — they handle routing, fetch data, and delegate to partials. + +### Front Matter + +```liquid +--- +slug: products/:id +method: post +layout: application +metadata: + title: "Product Details" +--- +``` + +| Property | Default | Notes | +|----------|---------|-------| +| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | +| `method` | `get` | `get`, `post`, `put`, `delete` | +| `layout` | `application` | Empty string for no layout | + +You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead. + +### Dynamic Routes + +| Pattern | URL | `context.params` | +|---------|-----|------------------| +| `products/:id` | `/products/123` | `{ "id": "123" }` | +| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` | +| `search(/:q)` | `/search/books` | `{ "q": "books" }` | + +### REST CRUD Convention + +| HTTP Method | URL Slug | Page File | GraphQL | Purpose | +|-------------|----------|-----------|---------|---------| +| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form | +| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource | +| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource | +| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form | +| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource | +| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource | +| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources | + +### CSRF Protection + +Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous). + +### GET Page Example + +```liquid +--- +slug: articles/:id +method: get +--- +{% liquid + function article = 'queries/articles/find', id: context.params.id + + if article == blank + render '404' + break + endif + + render 'articles/show', article: article +%} +``` + +### POST Page Example + +```liquid +--- +slug: articles +method: post +--- +{% liquid + function result = 'commands/articles/create', object: context.params.article + + if result.valid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname + redirect_to '/articles' + else + render 'articles/new', result: result + endif +%} +``` + +--- + +## 5. Partials & Layouts + +### Partials + +Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`). + +Partials MUST NOT have underscore-prefixed filenames. + +The render path maps: `render 'path/name'` → `app/views/partials/path/name.liquid`. + +### Layouts + +The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout. + +--- + +## 6. Commands (Business Logic) + +All business logic MUST be encapsulated in commands following the build → check → execute pattern. + +### Main Command + +```liquid +{% doc %} + @param object {object} - Article data +{% enddoc %} + +{% liquid + function object = 'commands/articles/create/build', object: object + function object = 'commands/articles/create/check', object: object + + if object.valid + function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object + endif + + return object +%} +``` + +### Build Stage + +Normalizes and structures input data: + +```liquid +{% doc %} + @param object {object} - form params +{% enddoc %} + +{% liquid + assign object['title'] = object.title + assign object['body'] = object.body + + return object +%} +``` + +### Check Stage + +Validates the built object: + +```liquid +{% doc %} + @param object {object} - form params +{% enddoc %} + +{% liquid + assign c = '{ "errors": {}, "valid": true }' | parse_json + + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title' + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body' + + assign object = object | hash_merge: valid: c.valid, errors: c.errors + + return object +%} +``` + +### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE) + +> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`). + +```liquid +{% comment %} WRONG — these partials do not exist: {% endcomment %} +{% function object = 'modules/core/commands/build', object: object %} +{% function object = 'modules/core/commands/check', object: object, + validators: '[{"name": "presence", "property": "title"}]' +%} + +{% comment %} CORRECT — only execute is shared: {% endcomment %} +{% if object.valid %} + {% function object = 'modules/core/commands/execute', + mutation_name: 'products/create', selection: 'record', object: object + %} +{% endif %} + +{% return object %} +``` + +### Events + +```liquid +{% comment %} Publish an event {% endcomment %} +{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %} + +{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %} +{% graphql _ = 'emails/send_confirmation', email: event.object.email %} +``` + +All inputs MUST be validated in commands before persisting. + +--- + +## 7. GraphQL + +GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively. + +### Query Wrapper Pattern + +```liquid +{% doc %} + @param id {string} - Article ID +{% enddoc %} + +{% liquid + graphql result = 'articles/find', id: id + return result.records.results | first +%} +``` + +### Search with Pagination + +```graphql +query search($page: Int = 1, $keyword: String) { + records( + page: $page + per_page: 20 + filter: { + table: { value: "article" } + properties: [{ name: "title", contains: $keyword }] + } + sort: { created_at: { order: DESC } } + ) { + total_pages + results { + id + title: property(name: "title") + body: property(name: "body") + } + } +} +``` + +All list queries MUST support `per_page` and `page` arguments for pagination. + +### Find by ID + +```graphql +query find($id: ID!) { + records( + per_page: 1 + filter: { + id: { value: $id } + table: { value: "article" } + } + ) { + results { + id + title: property(name: "title") + } + } +} +``` + +### Related Records (Avoids N+1) + +```graphql +results { + id + # belongs-to (single) + author: related_record(table: "user", join_on_property: "user_id") { + email + } + # has-many + comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") { + body: property(name: "body") + } +} +``` + +### Upload Property + +```graphql +image: property_upload(name: "image") { url } +``` + +### Mutations + +All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`: + +- `record: record_create(record: { table: "...", properties: [...] }) { id }` +- `record: record_update(id: $id, record: { properties: [...] }) { id }` +- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table" + +### Pagination Component + +```liquid +{% graphql result = 'products/search', page: context.params.page %} +{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %} +``` + +--- + +## 8. Schema + +Schema files define database tables in YAML at `app/schema/`. + +```yaml +# app/schema/article.yml +name: article +properties: + - name: title + type: string + - name: body + type: text + - name: published_at + type: datetime + - name: image + type: upload + options: + acl: public +``` + +### Property Types + +`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload` + +--- + +## 9. Liquid Reference + +### Tags + +```liquid +{% graphql result = 'query_name', arg: value %} +{% function result = 'path/to/partial', arg: value %} +{% render 'partial', var: value %} +{% doc %} @param name {Type} - description {% enddoc %} +{% return result %} +{% export my_var, namespace: 'my_ns' %} +{% parse_json data %}{"key": "value"}{% endparse_json %} +{% redirect_to '/path', status: 302 %} +{% session key = value %} +{% log variable, type: 'debug' %} +{% cache 'key', expire: 3600 %}...{% endcache %} +{% background source_name: 'job_name', priority: 'low' %}...{% endbackground %} +{% content_for_layout %} +{% theme_render_rc 'modules/common-styling/toasts' %} +``` + +**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is). + +### Output + +```liquid +{{ variable }} +{{ variable | html_safe }} +{% print variable %} +``` + +### Common Filters + +- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by` +- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys` +- **Dates:** `add_to_time`, `localize`, `is_date_in_past` +- **Validation:** `is_email_valid`, `is_json_valid` +- **Encoding:** `json`, `base64_encode`, `url_encode` + +### Coding Standards + +You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line. + +**Correct:** +```liquid +{% liquid + assign filtered = products | where: 'available', true | map: 'title' | first + assign price = product | where: 'id', pid | map: 'price' | first +%} +``` + +**WRONG (causes syntax errors):** +```liquid +{% liquid + assign filtered = products + | where: 'available', true + | map: 'title' + | first +%} +``` + +--- + +## 10. Global Context + +**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results. + +| Property | Description | +|----------|-------------| +| `context.params` | HTTP parameters (query string + body) | +| `context.session` | Server-side session storage | +| `context.location` | URL info (`pathname`, `search`, `host`) | +| `context.environment` | `staging` or `production` | +| `context.is_xhr` | `true` for AJAX requests | +| `context.authenticity_token` | CSRF token | +| `context.constants` | Environment constants (hidden from `{{ context }}` for security) | +| `context.page.metadata` | Page metadata from front matter | + +You MUST NOT use `context.current_user` directly — always use `modules/user/queries/user/current`. + +--- + +## 11. User Module (Authentication & Authorization) + +You MUST use the User Module for all authentication and authorization. You MUST NOT use `authorization_policies/` directly. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. + +### Built-in Roles + +- **Anonymous** — unauthenticated users +- **Authenticated** — any logged-in user +- **Superadmin** — bypasses ALL permission checks + +### Authorization Helpers + +```liquid +{% function profile = 'modules/user/queries/user/current' %} + +{% comment %} Check permission (returns true/false) {% endcomment %} +{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %} + +{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %} + +{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %} +``` + +> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`. + +### Custom Permissions + +Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`: + +```bash +mkdir -p app/modules/user/public/lib/queries/role_permissions +cp modules/user/public/lib/queries/role_permissions/permissions.liquid \ + app/modules/user/public/lib/queries/role_permissions/permissions.liquid +``` + +Define roles: +```liquid +{% parse_json data %} +{ + "admin": ["admin.view", "users.manage"], + "editor": ["article.create", "article.update"], + "superadmin": [] +} +{% endparse_json %} +{% return data %} +``` + +--- + +## 12. Core Module + +You MUST use pos-module-core for commands, events, and validators. + +--- + +## 13. Common Styling + +You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components. + +### Setup + +```liquid +{% comment %} In {% endcomment %} +{% render 'modules/common-styling/init' %} +``` +```html + +``` + +### File Upload Component + +```liquid +{% render 'modules/common-styling/forms/upload', + id: 'image', presigned_upload: presigned, name: 'image', + allowed_file_types: ['image/*'], max_number_of_files: 5 +%} +``` + +--- + +## 14. Translations (i18n) + +You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. + +--- + +## 15. Forms + +You MUST use HTML `` tags. You MUST NOT use `{% form %}`. + +Forms MUST include the CSRF token: +```html + +``` + +For PUT/DELETE, forms MUST use POST with a `_method` hidden field: +```html + + + + + +``` + +Form fields MUST use bracket notation for resource binding: +```html + +``` + +Access in page: `context.params.resource` + +HTML forms submit checkbox values as \"on\" (string), but GraphQL expects boolean field to be Boolean type, not string. + +--- + +## 16. Constants & Credentials + +You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`. + +### Setting Constants + +**Via CLI:** +```bash +pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev +pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev +pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev +``` + +**Via GraphQL:** +```graphql +mutation { + constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") { + name + } +} +``` + +### Accessing Constants in Liquid + +Constants are hidden from `{{ context }}` for security. You MUST access them explicitly: +```liquid +{{ context.constants.STRIPE_SK_KEY }} +{{ context.constants.API_BASE_URL }} +``` + +### Naming Conventions + +| Use Case | Example | +|----------|---------| +| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` | +| API URLs | `API_BASE_URL` | +| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` | + +Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically. + +--- + +## 17. Flash Messages & Toasts + +### Layout Setup (before ``) + +```liquid +{% liquid + function flash = 'modules/core/commands/session/get', key: 'sflash' + if context.location.pathname != flash.from or flash.force_clear + function _ = 'modules/core/commands/session/clear', key: 'sflash' + endif + render 'modules/common-styling/toasts', params: flash +%} +``` + +### Liquid Usage + +```liquid +{% liquid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname + redirect_to '/orders' +%} +``` + +### JavaScript Usage + +```javascript +new pos.modules.toast('success', 'Saved!'); +new pos.modules.toast('error', 'Failed'); +``` + +--- + +## 18. Notifications (Email/SMS) + +```liquid +{% comment %} app/emails/order_confirmation.liquid {% endcomment %} +--- +to: {{ data.email }} +from: shop@example.com +subject: "Order #{{ data.order_id }}" +layout: mailer +--- +

Thank you for your order!

+``` + +Emails SHOULD be sent asynchronously using events + consumers. + +--- + +## 19. Payments (Stripe) + +### Install + +```bash +pos-cli modules install payments && pos-cli modules install payments_stripe +pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev +``` + +### Create Transaction + +```liquid +{% function transaction = 'modules/payments/commands/transactions/create', + gateway: 'stripe', email: email, line_items: items, + success_url: '/thank-you', cancel_url: '/cart' +%} +{% function url = 'modules/payments/queries/pay_url', transaction: transaction %} +{% redirect_to url, status: 303 %} +``` + +Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed` + +**Test card:** `4242 4242 4242 4242`, any future date, any CVC. + +--- + +## 20. Migrations + +Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications. + +### File Structure + +``` +app/migrations/ +├── 20240115120000_seed_initial_data.liquid +├── 20240116093000_add_default_categories.liquid +└── 20240120150000_init_staging_constants.liquid +``` + +Files MUST be named with UTC timestamp prefix for chronological execution. + +### Creating a Migration + +```bash +pos-cli migrations generate dev init_staging_constants +# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid +``` + +### Example: Initialize Staging Constants + +```liquid +{% liquid + if context.environment == 'staging' + graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123' + graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com' + endif +%} +``` + +### Example: Seed Data + +```liquid +{% parse_json categories %} +["Electronics", "Clothing", "Books"] +{% endparse_json %} + +{% for category in categories %} + {% graphql _ = 'categories/create', name: category %} +{% endfor %} +``` + +### Running Migrations + +- **Automatic:** Pending migrations run on `pos-cli deploy` +- **Manual:** `pos-cli migrations run TIMESTAMP dev` + +### Migration States + +- **pending** — not yet executed (runs on next deploy) +- **done** — successfully completed (will not run again) +- **error** — failed (can edit and retry) + +For large data imports, use Data Import/Export instead of migrations. + +--- + +## 21. Testing + +Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. + +Every new feature MUST have unit tests for commands. + +```liquid +{% function result = 'commands/products/create', title: "Test" %} +{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %} +{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %} +{% return contract %} +``` + +Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. + +--- + +## 22. CLI Commands + +```bash +# Deployment +pos-cli deploy dev + +# Sync (MUST sync every file after modification) +pos-cli sync dev + +# Logs +pos-cli logs dev + +# Linting (MUST run after EVERY file change) +platformos-check + +# Run Liquid inline +pos-cli exec liquid dev '' + +# Run GraphQL inline +pos-cli exec graphql dev '' + +# Tests +pos-cli test run staging + +# Modules +pos-cli modules install +pos-cli modules download + +# Constants +pos-cli constants set --name KEY --value "value" dev + +# Generate CRUD +pos-cli generate run modules/core/generators/crud --include-views + +# Migrations +pos-cli migrations generate dev +pos-cli migrations run TIMESTAMP dev +``` + +--- + +## 23. Modules Reference + +| Module | Install | Purpose | Required | +|--------|---------|---------|----------| +| `core` | Required | Commands, events, validators | YES | +| `user` | Required | Auth, RBAC, OAuth2 | YES | +| `common-styling` | Required | CSS, components | YES | +| `tests` | Optional | Testing framework | YES (for testing) | +| `payments` + `payments_stripe` | Optional | Stripe payments | No | +| `chat` | Optional | WebSocket messaging | No | +| `openai` | Optional | OpenAI integration | No | + +--- + +## 24. Forbidden Behaviors + +You MUST NOT: +- Edit files in `./modules/` (read-only) +- Break long lines in `{% liquid %}` blocks (causes syntax errors) +- Invent Liquid tags, filters, or GraphQL types that do not exist +- Use `{% form %}` tag (use HTML `
` only) +- Bypass security (CSRF tokens, authorization) +- Access databases directly outside GraphQL +- Deploy without running `platformos-check` +- Sync files outside `./app/` +- Use `authorization_policies/` directly (use pos-module-user) +- Use `context.current_user` directly (use user module queries) +- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling) +- Hardcode API keys, secrets, or environment-specific URLs +- Hardcode user-facing text in partials (use translations) +- Put HTML, JS, or CSS in page files +- Call GraphQL from partials +- Put raw GraphQL in pages (use `.graphql` files) +- Create or modify application files outside the `app/` directory + +--- + +## 25. Pre-Flight Checklist + +Before every change, verify: + +- [ ] No underscore prefix in partial filenames +- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid` +- [ ] Pages have ONE HTTP method each +- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files) +- [ ] No HTML/JS/CSS in pages +- [ ] No hardcoded text in partials (use translations) +- [ ] `platformos-check` passes with 0 errors +- [ ] Every file synced after modification +- [ ] All list queries support pagination (`per_page`, `page`) +- [ ] All inputs validated in commands before persisting +- [ ] CSS/JS minified, `asset_url` used for cache busting + +### Asset URL Usage + +```liquid +{{ 'images/img.png' | asset_url }} +``` diff --git a/src/http-server.js b/src/http-server.js index c6c4208..c0bdea4 100644 --- a/src/http-server.js +++ b/src/http-server.js @@ -10,7 +10,7 @@ import { HTTP_MAX_BODY } from './core/constants.js'; import { buildDashboardHtml } from './dashboard.js'; import { getProjectMap } from './tools/project-map.js'; import { buildDependencyGraph } from './core/dependency-graph.js'; -import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory } from './core/analytics-queries.js'; +import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory, ruleDrilldown } from './core/analytics-queries.js'; import { ruleScores, suggestedRules, retrieveCasesByCheck, generateRuleTemplate } from './core/case-base.js'; import { addPromotedRule, removePromotedRule, listPromotedRules } from './core/rules/promoted-rules.js'; import { reloadRules, loadAllRules } from './core/rules/index.js'; @@ -188,6 +188,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re return handleRuleScores(analyticsStore, url, res); } + if (method === 'GET' && url.pathname === '/api/analytics/rule-drilldown') { + return handleRuleDrilldown(analyticsStore, url, res); + } + if (method === 'GET' && url.pathname === '/api/analytics/suggested-rules') { return handleSuggestedRules(analyticsStore, res); } @@ -1054,6 +1058,19 @@ function handleRuleScores(analyticsStore, url, res) { } } +function handleRuleDrilldown(analyticsStore, url, res) { + if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); + try { + const ruleId = url.searchParams.get('rule_id'); + if (!ruleId) return sendJson(res, 400, { error: 'rule_id parameter required' }); + const limit = Math.min(parseInt(url.searchParams.get('limit') || '30', 10), 100); + const data = ruleDrilldown(analyticsStore, ruleId, { limit }); + sendJson(res, 200, data); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + function handleSuggestedRules(analyticsStore, res) { if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); try { diff --git a/src/tools/analyze-project.js b/src/tools/analyze-project.js index bda4208..8c37c95 100644 --- a/src/tools/analyze-project.js +++ b/src/tools/analyze-project.js @@ -116,6 +116,32 @@ export const analyzeProjectTool = { } } + // Catch diagnostics from pos-cli check that target files outside + // the checkable set (e.g. MatchingTranslations in .yml files). + const fileSet = new Set(files); + const unattributed = new Map(); + for (const d of [...allResults.errors, ...allResults.warnings, ...allResults.infos]) { + if (!d._filePath) continue; + const rel = d._filePath.startsWith(ctx.directory) + ? d._filePath.slice(ctx.directory.length + 1) + : d._filePath; + if (fileSet.has(rel)) continue; + if (!unattributed.has(rel)) unattributed.set(rel, { errors: 0, warnings: 0, infos: 0 }); + const counts = unattributed.get(rel); + counts[d.severity === 'error' ? 'errors' : d.severity === 'warning' ? 'warnings' : 'infos']++; + } + for (const [path, counts] of unattributed) { + const hasRelevant = + counts.errors > 0 || + (minRank <= 2 && counts.warnings > 0) || + (minRank <= 1 && counts.infos > 0); + if (hasRelevant) { + const entry = { path, errors: counts.errors, warnings: counts.warnings }; + if (minRank <= 1) entry.infos = counts.infos; + fileResults.push(entry); + } + } + // Schema validation — validate all .yml files in app/schema/ let schemasScanned = 0; try { @@ -220,7 +246,7 @@ export const analyzeProjectTool = { } return { - files_scanned: filesScanned + schemasScanned, + files_scanned: filesScanned + schemasScanned + unattributed.size, files: fileResults, fix_order, blocking_files: blockingFiles, diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js index e26fd2a..622a9ae 100644 --- a/src/tools/validate-code.js +++ b/src/tools/validate-code.js @@ -676,6 +676,7 @@ explicitly only if you are validating a file that is NOT part of the most recent fp, template_fp: tFp, file: file_path, + check: d.check || null, content_hash: contentHash, hint_md_hash: hintHash, hint_rule_id: d.rule_id || d.check || null, From e393cff8baeb15046542bdf35de66ba574016dcb Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Tue, 21 Apr 2026 17:34:42 +0200 Subject: [PATCH 12/20] Finished neuro-symbolic engine improvements 1-5 --- src/core/case-base.js | 202 +- src/core/engine-mode.js | 85 + src/core/error-enricher.js | 3 +- src/core/lsp-client.js | 54 +- src/core/rules/MissingPartial.js | 16 +- src/core/rules/TranslationKeyExists.js | 11 +- src/core/rules/UndefinedObject.js | 37 +- src/core/rules/UnknownFilter.js | 35 +- src/core/rules/engine.js | 2 + src/core/rules/index.js | 5 +- src/core/rules/promoted-rules.js | 52 +- src/core/rules/queries.js | 29 + src/core/session-events.js | 1 + src/core/translation-validator.js | 172 + src/dashboard.js | 91 +- src/data/hints/TranslationKeyExists.md | 14 +- .../UnrecognizedRenderPartialArguments.md | 18 + src/data/references/pages/gotchas.md | 2 +- .../platformos-development-guide-full.md | 3154 ++++++++++++++ .../resources/platformos-development-guide.md | 3776 +++++------------ .../platformos-development-guide.md~ | 1636 +++++++ src/http-server.js | 41 +- src/server.js | 38 +- src/tools.js | 23 +- src/tools/server-status.js | 2 + src/tools/validate-code.js | 35 +- .../project/app/views/pages/test.html.liquid | 6 + tests/unit/case-base-integration.test.js | 6 +- tests/unit/engine-mode.test.js | 179 + tests/unit/guard-synthesis.test.js | 301 ++ tests/unit/lsp-stale-diagnostics.test.js | 59 +- tests/unit/promoted-rules.test.js | 445 ++ tests/unit/translation-validator.test.js | 114 + 33 files changed, 7874 insertions(+), 2770 deletions(-) create mode 100644 src/core/engine-mode.js create mode 100644 src/core/translation-validator.js create mode 100644 src/data/hints/UnrecognizedRenderPartialArguments.md create mode 100644 src/data/resources/platformos-development-guide-full.md create mode 100644 src/data/resources/platformos-development-guide.md~ create mode 100644 tests/fixtures/project/app/views/pages/test.html.liquid create mode 100644 tests/unit/engine-mode.test.js create mode 100644 tests/unit/guard-synthesis.test.js create mode 100644 tests/unit/translation-validator.test.js diff --git a/src/core/case-base.js b/src/core/case-base.js index 3f4b8f7..c81347c 100644 --- a/src/core/case-base.js +++ b/src/core/case-base.js @@ -16,8 +16,11 @@ * view over the existing tables — no additional schema needed. */ +import { classifyFileType } from './rules/queries.js'; + const MIN_CASES = 3; const RULE_DISABLE_THRESHOLD = 0.15; +const GUARD_MIN_SAMPLES = 5; /** * F1: Retrieve cases for a diagnostic template. @@ -298,15 +301,112 @@ export function suggestedRules(store, existingRuleChecks = new Set(), { minCases return suggestions; } +/** + * F4: Synthesize guard predicates from historical diagnostic data. + * + * Analyzes patterns in file paths and diagnostic params to produce a `when` + * object compatible with promoted-rules JSON format (see compileWhen()). + * + * Thresholds: + * param_equals — ≥90% of values identical + * param_startsWith — ≥80% share a common prefix (len ≥ 2) + * param_contains — ≥80% contain a common substring (len ≥ 3) + * file_type — ≥80% share the same classified type + * + * @param {object} store - Analytics store + * @param {string} check - Check name + * @param {string} templateFp - Template fingerprint + * @param {object} [opts] + * @param {number} [opts.minSamples=5] - Minimum samples to infer a guard + * @returns {object} JSON `when` object for promoted rules + */ +export function synthesizeGuardPredicate(store, check, templateFp, { minSamples = GUARD_MIN_SAMPLES } = {}) { + const when = {}; + + const fileRows = store.query(` + SELECT DISTINCT file FROM diagnostics + WHERE check_name = ? AND template_fp = ? AND suppressed = 0 + `, [check, templateFp]); + + if (fileRows.length >= minSamples) { + const types = fileRows.map(r => classifyFileType(r.file)); + const dominant = dominantValue(types); + if (dominant && dominant.ratio >= 0.8 && dominant.value !== 'unknown') { + when.file_type = dominant.value; + } + } + + const eventRows = store.query(` + SELECT payload FROM events + WHERE kind = 'validator_emit' + AND json_extract(payload, '$.check') = ? + AND json_extract(payload, '$.template_fp') = ? + `, [check, templateFp]); + + const paramSamples = []; + for (const row of eventRows) { + try { + const p = JSON.parse(row.payload); + if (p.params && typeof p.params === 'object' && Object.keys(p.params).length > 0) { + paramSamples.push(p.params); + } + } catch { /* skip malformed */ } + } + + if (paramSamples.length >= minSamples) { + const keys = new Set(); + for (const s of paramSamples) { + for (const k of Object.keys(s)) keys.add(k); + } + + for (const key of keys) { + const values = paramSamples + .map(s => s[key]) + .filter(v => typeof v === 'string' && v.length > 0); + + if (values.length < minSamples) continue; + + const top = dominantValue(values); + if (top && top.ratio >= 0.9) { + if (!when.param_equals) when.param_equals = {}; + when.param_equals[key] = top.value; + continue; + } + + const prefix = findDominantPrefix(values, 2); + if (prefix) { + if (!when.param_startsWith) when.param_startsWith = {}; + when.param_startsWith[key] = prefix; + continue; + } + + const substr = findDominantSubstring(values, 3); + if (substr) { + if (!when.param_contains) when.param_contains = {}; + when.param_contains[key] = substr; + } + } + } + + return when; +} + /** * F3: Generate a rule template for a suggested rule. * Produces a JS code template that can be saved as a draft for human review. + * + * @param {object} suggestion - From suggestedRules() + * @param {object} [guards={}] - Synthesized when clause from synthesizeGuardPredicate() */ -export function generateRuleTemplate(suggestion) { +export function generateRuleTemplate(suggestion, guards = {}) { const { check, template_fp } = suggestion; const safeCheck = check.replace(/[^a-zA-Z0-9_]/g, '_'); const shortFp = template_fp.slice(0, 8); + const whenBody = Object.keys(guards).length > 0 + ? renderGuardsAsJs(guards) + : ' // TODO: Add guard predicate based on diagnostic params\n return true;'; + return `// Suggested rule — generated from case-base analysis // Template fingerprint: ${template_fp} // Resolution rate: ${(suggestion.resolution_rate * 100).toFixed(0)}% across ${suggestion.total_outcomes} outcomes @@ -319,8 +419,7 @@ export function generateRuleTemplate(suggestion) { check: '${check}', priority: 50, when: (diag) => { - // TODO: Add guard predicate based on diagnostic params - return true; +${whenBody} }, apply: (diag) => { return { @@ -387,3 +486,100 @@ export function resolveProbation(store, { minOutcomes = 20 } = {}) { return resolutions; } + +// ── Guard synthesis helpers ──────────────────────────────────────────────── + +function dominantValue(arr) { + const freq = new Map(); + for (const v of arr) freq.set(v, (freq.get(v) || 0) + 1); + let best = null; + for (const [value, count] of freq) { + if (!best || count > best.count) best = { value, count }; + } + return best ? { value: best.value, count: best.count, ratio: best.count / arr.length } : null; +} + +function findDominantPrefix(values, minLen) { + if (values.length === 0) return null; + const threshold = values.length * 0.8; + let best = null; + for (const val of values) { + for (let len = val.length; len >= minLen; len--) { + const prefix = val.slice(0, len); + if (best && prefix.length <= best.length) break; + const matchCount = values.filter(v => v.startsWith(prefix)).length; + if (matchCount >= threshold) { + best = prefix; + break; + } + } + } + return best; +} + +function findDominantSubstring(values, minLen) { + if (values.length === 0) return null; + const shortest = values.reduce((a, b) => a.length <= b.length ? a : b); + let best = null; + for (let len = shortest.length; len >= minLen; len--) { + for (let start = 0; start <= shortest.length - len; start++) { + const candidate = shortest.slice(start, start + len); + const matchCount = values.filter(v => v.includes(candidate)).length; + if (matchCount / values.length >= 0.8) { + if (!best || candidate.length > best.length) best = candidate; + return best; + } + } + } + return best; +} + +const FILE_TYPE_PATH_HINT = { + page: '/pages/', + partial: '/partials/', + layout: '/layouts/', + command: '/commands/', + query: '/queries/', + graphql: '/graphql/', + schema: '/schema/', + module: 'modules/', +}; + +function renderGuardsAsJs(guards) { + const conditions = []; + + if (guards.param_equals) { + for (const [k, v] of Object.entries(guards.param_equals)) { + conditions.push(`diag.params?.${k} === ${JSON.stringify(v)}`); + } + } + + if (guards.param_startsWith) { + for (const [k, v] of Object.entries(guards.param_startsWith)) { + conditions.push(`diag.params?.${k}?.startsWith(${JSON.stringify(v)})`); + } + } + + if (guards.param_contains) { + for (const [k, v] of Object.entries(guards.param_contains)) { + conditions.push(`diag.params?.${k}?.includes(${JSON.stringify(v)})`); + } + } + + if (guards.file_type) { + const hint = FILE_TYPE_PATH_HINT[guards.file_type]; + if (hint) { + conditions.push(`diag.file?.includes(${JSON.stringify(hint)})`); + } + } + + if (conditions.length === 0) { + return ' // No guards synthesized — review and narrow this rule\n return true;'; + } + + if (conditions.length === 1) { + return ` return ${conditions[0]};`; + } + + return ` return ${conditions.join(' &&\n ')};`; +} diff --git a/src/core/engine-mode.js b/src/core/engine-mode.js new file mode 100644 index 0000000..a8bdadb --- /dev/null +++ b/src/core/engine-mode.js @@ -0,0 +1,85 @@ +/** + * Engine mode — global toggle for the neuro-symbolic write side. + * + * Two modes: + * 'adaptive' — auto-disabling, case-base scoring, promoted rules, probation + * 'static' — all rules fire at raw confidence, no promoted rules loaded + * + * Analytics data collection runs in BOTH modes. Only the consumption + * of analytics (scoring, disabling, promoting) is gated. + */ + +import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'; +import { join } from 'node:path'; + +const MODE_FILE = 'engine-mode.json'; +const VALID_MODES = new Set(['adaptive', 'static']); + +let _mode = 'static'; +let _listeners = []; + +export function getEngineMode() { + return _mode; +} + +export function isAdaptive() { + return _mode === 'adaptive'; +} + +export function setEngineMode(mode, { projectDir, onTransition } = {}) { + if (!VALID_MODES.has(mode)) { + throw new Error(`Invalid engine mode: '${mode}'. Must be 'adaptive' or 'static'.`); + } + const prev = _mode; + if (prev === mode) return; + + _mode = mode; + + if (projectDir) { + persistEngineMode(projectDir, mode); + } + + if (onTransition) { + onTransition(prev, mode); + } + + for (const fn of _listeners) { + try { fn(mode, prev); } catch { /* listener failure is non-fatal */ } + } +} + +export function onEngineModeChange(fn) { + _listeners.push(fn); + return () => { + _listeners = _listeners.filter(f => f !== fn); + }; +} + +export function loadEngineMode(projectDir) { + const filePath = join(projectDir, '.pos-supervisor', MODE_FILE); + if (!existsSync(filePath)) return _mode; + + try { + const raw = JSON.parse(readFileSync(filePath, 'utf-8')); + if (VALID_MODES.has(raw?.mode)) { + _mode = raw.mode; + } + } catch { /* malformed file — keep current mode */ } + + return _mode; +} + +export function persistEngineMode(projectDir, mode) { + const dir = join(projectDir, '.pos-supervisor'); + if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, MODE_FILE), + JSON.stringify({ mode, updated_at: new Date().toISOString() }, null, 2) + '\n', + 'utf-8', + ); +} + +export function resetEngineMode() { + _mode = 'static'; + _listeners = []; +} diff --git a/src/core/error-enricher.js b/src/core/error-enricher.js index e705f19..b17428f 100644 --- a/src/core/error-enricher.js +++ b/src/core/error-enricher.js @@ -57,7 +57,7 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI if (factGraph && hasRules(diagnostic.check)) { const params = extractParams(diagnostic.check, diagnostic.message); const tmplFp = templateOf(diagnostic.check, diagnostic.message); - const diag = { check: diagnostic.check, params, message: diagnostic.message, file: filePath, line: diagnostic.line, template_fp: tmplFp }; + const diag = { check: diagnostic.check, params, message: diagnostic.message, file: filePath, line: diagnostic.line, column: diagnostic.column ?? 0, template_fp: tmplFp }; const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore }; const ruleResult = runRules(diag, facts); if (ruleResult) { @@ -67,6 +67,7 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI if (ruleResult.see_also) result.see_also = ruleResult.see_also; if (ruleResult.confidence != null) result.confidence = ruleResult.confidence; if (ruleResult.case_base_signal) result.case_base_signal = ruleResult.case_base_signal; + if (ruleResult.fixes?.length > 0) result.fixes = ruleResult.fixes; attachSeeAlso(result, content); return result; } diff --git a/src/core/lsp-client.js b/src/core/lsp-client.js index 0bf75e5..9c3cdd8 100644 --- a/src/core/lsp-client.js +++ b/src/core/lsp-client.js @@ -125,17 +125,11 @@ export class PlatformOSLSPClient { if (msg.method === 'textDocument/publishDiagnostics') { const uri = msg.params.uri; const diags = msg.params.diagnostics ?? []; - const waiter = this.#diagWaiters.get(uri); - if (waiter?.gate && !waiter.gate()) { - // Pre-barrier notification — stale, discard entirely - return; - } this.#diagnostics.set(uri, diags); + const waiter = this.#diagWaiters.get(uri); if (waiter?.onDiag) { - // Settle-based waiter: notify but keep alive for updates waiter.onDiag(diags); } else if (waiter) { - // Simple waiter: resolve immediately this.#diagWaiters.delete(uri); clearTimeout(waiter.timer); waiter.resolve(diags); @@ -257,48 +251,28 @@ export class PlatformOSLSPClient { * Uses a barrier request to guarantee freshness. The LSP processes stdin * messages sequentially, so after sending: * 1. didOpen/didChange (our content) - * 2. hover request (barrier) - * the LSP must process (1) before responding to (2). Any publishDiagnostics - * arriving in stdout BEFORE the hover response is from a prior analysis - * (stale); anything AFTER is from our content (fresh). - * - * The barrier's resolve callback runs synchronously during #drain (same - * synchronous loop as message processing), so the gate flag is set before - * any subsequent publishDiagnostics in the same buffer chunk is handled. - */ - /** * Sync document content and wait for fresh diagnostics. * - * Uses a two-layer strategy to guarantee freshness: - * - * **Layer 1 — Barrier (hover fence):** The LSP processes stdin messages - * sequentially, so after sending didOpen/didChange + hover, the hover - * response proves the LSP received our content. Any publishDiagnostics - * arriving BEFORE the hover response is from a prior analysis (stale) - * and is discarded by the gate. - * - * **Layer 2 — Settle window:** The LSP may use async background workers - * for analysis. A stale analysis that was already in-flight can publish - * diagnostics AFTER the barrier. The settle window (200ms) ensures we - * accept the LAST publishDiagnostics within a quiet period, not just - * the first. If the LSP sends stale-then-fresh in quick succession, - * the settle timer resets on each arrival and we resolve with the - * latest (fresh) set. + * Sends a hover request as a synchronization fence — the LSP must process + * didOpen/didChange before responding to hover, proving it received our + * content. A settle window (500ms quiet period) then waits for the LAST + * publishDiagnostics batch, accepting all arrivals regardless of barrier + * timing. The LSP may emit valid diagnostics before the hover response + * when analysis is fast, so no pre-barrier filtering is applied. */ awaitDiagnostics(uri, text, timeoutMs = LSP_DIAGNOSTICS_TIMEOUT_MS) { this.syncDoc(uri, text); this.#diagnostics.delete(uri); - // ── Barrier: hover request used as a synchronization fence ── - let barrierPassed = false; + // ── Barrier: hover request as sync fence (ensures LSP processes our content) ── const barrierId = ++this.#reqId; const barrierTimer = setTimeout(() => { - if (this.#pending.delete(barrierId)) barrierPassed = true; + this.#pending.delete(barrierId); }, Math.min(timeoutMs, LSP_BARRIER_TIMEOUT_MS)); this.#pending.set(barrierId, { - resolve: () => { clearTimeout(barrierTimer); barrierPassed = true; }, - reject: () => { clearTimeout(barrierTimer); barrierPassed = true; }, + resolve: () => { clearTimeout(barrierTimer); }, + reject: () => { clearTimeout(barrierTimer); }, }); this.#send({ jsonrpc: '2.0', id: barrierId, @@ -306,7 +280,7 @@ export class PlatformOSLSPClient { params: { textDocument: { uri }, position: { line: 0, character: 0 } }, }); - // ── Diagnostic waiter: barrier gate + settle window ── + // ── Diagnostic waiter: settle window resolves with latest batch ── const SETTLE_MS = DIAGNOSTICS_SETTLE_MS; return new Promise((resolve) => { let latestDiags = null; @@ -328,15 +302,13 @@ export class PlatformOSLSPClient { this.#diagWaiters.set(uri, { timer: mainTimer, settleTimer: null, - gate: () => barrierPassed, onDiag: (diags) => { latestDiags = diags; if (settleTimer) clearTimeout(settleTimer); settleTimer = setTimeout(() => finish(latestDiags), SETTLE_MS); - // Store ref for crash cleanup this.#diagWaiters.get(uri).settleTimer = settleTimer; }, - resolve: (diags) => finish(diags), // crash cleanup path + resolve: (diags) => finish(diags), }); }); } diff --git a/src/core/rules/MissingPartial.js b/src/core/rules/MissingPartial.js index 7f48b5e..7c8d0d0 100644 --- a/src/core/rules/MissingPartial.js +++ b/src/core/rules/MissingPartial.js @@ -24,7 +24,10 @@ export const rules = [ return { rule_id: 'MissingPartial.module_path', hint_md: `\`${name}\` is a module path — cannot create files inside installed modules. Use \`module_info\` to verify the correct path.`, - fixes: [], + fixes: [{ + type: 'guidance', + description: `Cannot create files inside module \`${moduleName}\`. Call \`module_info("${moduleName}", "api")\` to find the correct partial path exported by this module.`, + }], confidence: 0.9, see_also: { tool: 'module_info', @@ -50,7 +53,10 @@ export const rules = [ return { rule_id: 'MissingPartial.file_exists', hint_md: `File \`${path}\` exists but the linter still reports it as missing. Check that the file is not empty, has no syntax errors, and the path in the render/function tag matches exactly.`, - fixes: [], + fixes: [{ + type: 'guidance', + description: `File \`${path}\` exists on disk. Verify: (1) file is not empty, (2) no Liquid syntax errors inside it, (3) the render/function tag path matches exactly (case-sensitive).`, + }], confidence: 0.7, }; }, @@ -89,10 +95,14 @@ export const rules = [ const suggestions = nearest.map(n => `\`${n.name}\` (distance: ${n.distance})`).join(', '); const tag = type === 'partial' ? 'render' : 'function'; + const bestMatch = nearest[0].name; return { rule_id: 'MissingPartial.suggest_nearest', hint_md: `\`${name}\` not found. Did you mean: ${suggestions}? Fix the name in the \`{% ${tag} %}\` tag.`, - fixes: [], + fixes: [{ + type: 'guidance', + description: `Replace \`${name}\` with \`${bestMatch}\` in the \`{% ${tag} '${name}' %}\` tag.`, + }], confidence: 0.6, }; }, diff --git a/src/core/rules/TranslationKeyExists.js b/src/core/rules/TranslationKeyExists.js index 5040e20..8b1528d 100644 --- a/src/core/rules/TranslationKeyExists.js +++ b/src/core/rules/TranslationKeyExists.js @@ -25,11 +25,15 @@ export const rules = [ const nearest = nearestByLevenshtein(key, keys, 3); if (nearest.length === 0) return null; + const bestMatch = nearest[0].name; const suggestions = nearest.map(n => `\`${n.name}\``).join(', '); return { rule_id: 'TranslationKeyExists.suggest_nearest', hint_md: `Translation key \`${key}\` not found. Did you mean: ${suggestions}? Or add it to \`app/translations/en.yml\`.`, - fixes: [], + fixes: [{ + type: 'guidance', + description: `Replace \`${key}\` with \`${bestMatch}\` in the \`{{ '${key}' | t }}\` filter, or add the missing key to \`app/translations/en.yml\`.`, + }], confidence: 0.7, }; }, @@ -56,7 +60,10 @@ export const rules = [ return { rule_id: 'TranslationKeyExists.create_key', hint_md: `Add translation key \`${key}\` to \`app/translations/en.yml\`:\n\`\`\`yaml\n${snippet}\n\`\`\``, - fixes: [], + fixes: [{ + type: 'guidance', + description: `Add the following YAML to \`app/translations/en.yml\`:\n${snippet}`, + }], confidence: 0.8, }; }, diff --git a/src/core/rules/UndefinedObject.js b/src/core/rules/UndefinedObject.js index f80d6d0..4583677 100644 --- a/src/core/rules/UndefinedObject.js +++ b/src/core/rules/UndefinedObject.js @@ -26,11 +26,29 @@ export const rules = [ const kb = getCheckKnowledge('UndefinedObject', 'default'); + const fixes = []; + if (info?.replacement) { + fixes.push({ + type: 'text_edit', + range: { + start: { line: diag.line, character: diag.column }, + end: { line: diag.line, character: diag.column + name.length }, + }, + new_text: info.replacement, + description: `Replace Shopify object \`${name}\` with \`${info.replacement}\``, + }); + } else { + fixes.push({ + type: 'guidance', + description: `\`${name}\` is a Shopify theme object. Use \`{% graphql %}\` to fetch data and \`context.*\` for request/user data.`, + }); + } + return { rule_id: 'UndefinedObject.shopify_object', hint_md: `${kb?.shopify_guidance ?? suggestion}\n\n${suggestion}`, suggestion, - fixes: [], + fixes, confidence: 0.95, see_also: { tool: 'domain_guide', @@ -58,7 +76,15 @@ export const rules = [ return { rule_id: 'UndefinedObject.context_prefix', hint_md: `Use \`context.${name}\` instead of bare \`${name}\`. In pages, all built-in objects require the \`context.\` prefix: \`context.params\`, \`context.session\`, \`context.current_user\`, \`context.page\`.`, - fixes: [], + fixes: [{ + type: 'text_edit', + range: { + start: { line: diag.line, character: diag.column }, + end: { line: diag.line, character: diag.column + name.length }, + }, + new_text: `context.${name}`, + description: `Replace \`${name}\` with \`context.${name}\``, + }], confidence: 0.9, }; }, @@ -83,7 +109,12 @@ export const rules = [ return { rule_id: 'UndefinedObject.declare_param', hint_md: `Variable \`${name}\` is not defined. In ${fileType}s, all variables must be passed explicitly. Add a \`{% doc %}\` block: \`{% doc %} @param {object} ${name} {% enddoc %}\` and pass it from the caller.`, - fixes: [], + fixes: [{ + type: 'insert', + position: { line: 0, character: 0 }, + text: `{% doc %}\n @param {object} ${name}\n{% enddoc %}\n`, + description: `Add \`@param {object} ${name}\` declaration in a {% doc %} block at the top of the file`, + }], confidence: 0.85, }; }, diff --git a/src/core/rules/UnknownFilter.js b/src/core/rules/UnknownFilter.js index 31ff939..3f08942 100644 --- a/src/core/rules/UnknownFilter.js +++ b/src/core/rules/UnknownFilter.js @@ -23,7 +23,10 @@ export const rules = [ return { rule_id: 'UnknownFilter.tag_confusion', hint_md: `\`${name}\` is a tag, not a filter. Use \`{% ${name} ... %}\` instead of \`| ${name}\`.`, - fixes: [], + fixes: [{ + type: 'guidance', + description: `Replace \`| ${name}\` with block syntax \`{% ${name} ... %}\`. This is a structural change — the filter pipe must become a tag block.`, + }], confidence: 0.95, }; }, @@ -44,11 +47,29 @@ export const rules = [ ? `\`${name}\` is a Shopify filter — not in platformOS. Use \`${info.replacement}\` instead.${info.note ? ` ${info.note}` : ''}` : `\`${name}\` is a Shopify-specific filter — not in platformOS.${info?.note ? ` ${info.note}` : ''}`; + const fixes = []; + if (info?.replacement) { + fixes.push({ + type: 'text_edit', + range: { + start: { line: diag.line, character: diag.column }, + end: { line: diag.line, character: diag.column + name.length }, + }, + new_text: info.replacement, + description: `Replace Shopify filter \`${name}\` with platformOS equivalent \`${info.replacement}\``, + }); + } else { + fixes.push({ + type: 'guidance', + description: `\`${name}\` is Shopify-specific. Check platformOS docs for equivalent functionality.`, + }); + } + return { rule_id: 'UnknownFilter.shopify_filter', hint_md: suggestion, suggestion, - fixes: [], + fixes, confidence: 0.9, see_also: { tool: 'lookup', @@ -83,7 +104,15 @@ export const rules = [ return { rule_id: 'UnknownFilter.suggest_nearest', hint_md: `Did you mean \`${closest.name}\`? ${closest.syntax || closest.summary}`, - fixes: [], + fixes: [{ + type: 'text_edit', + range: { + start: { line: diag.line, character: diag.column }, + end: { line: diag.line, character: diag.column + name.length }, + }, + new_text: closest.name, + description: `Replace \`${name}\` with \`${closest.name}\``, + }], confidence: 0.6, }; } diff --git a/src/core/rules/engine.js b/src/core/rules/engine.js index ebae059..d591f9f 100644 --- a/src/core/rules/engine.js +++ b/src/core/rules/engine.js @@ -25,6 +25,7 @@ */ import { scoreRule } from '../case-base.js'; +import { isAdaptive } from '../engine-mode.js'; const _registry = new Map(); const _disabledRules = new Set(); @@ -86,6 +87,7 @@ export function runRules(diag, facts, { multiMatch = false } = {}) { } function applyCaseBaseScoring(result, diag, facts) { + if (!isAdaptive()) return; if (!facts.analyticsStore || !result.rule_id) return; try { const templateFp = diag.template_fp ?? null; diff --git a/src/core/rules/index.js b/src/core/rules/index.js index c4e3daf..6eb381c 100644 --- a/src/core/rules/index.js +++ b/src/core/rules/index.js @@ -7,6 +7,7 @@ */ import { registerRules, clearRules, ruleCount } from './engine.js'; import { loadPromotedRules } from './promoted-rules.js'; +import { isAdaptive } from '../engine-mode.js'; import { rules as MissingPartialRules } from './MissingPartial.js'; import { rules as UndefinedObjectRules } from './UndefinedObject.js'; import { rules as UnknownFilterRules } from './UnknownFilter.js'; @@ -42,7 +43,7 @@ export function loadAllRules() { export function initPromotedRules(projectDir) { _promotedProjectDir = projectDir; - loadPromotedRules(projectDir); + if (isAdaptive()) loadPromotedRules(projectDir); } export function reloadRules(projectDir) { @@ -50,7 +51,7 @@ export function reloadRules(projectDir) { _loaded = false; loadAllRules(); const dir = projectDir ?? _promotedProjectDir; - if (dir) loadPromotedRules(dir); + if (dir && isAdaptive()) loadPromotedRules(dir); } export { ruleCount }; diff --git a/src/core/rules/promoted-rules.js b/src/core/rules/promoted-rules.js index c66b743..4e21728 100644 --- a/src/core/rules/promoted-rules.js +++ b/src/core/rules/promoted-rules.js @@ -13,7 +13,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs'; import { join } from 'node:path'; import { registerRules } from './engine.js'; -import { classifyPath } from './queries.js'; +import { classifyPath, classifyFileType, callerCount, isOrphan, hasDocParams } from './queries.js'; const PROMOTED_RULES_FILE = 'promoted-rules.json'; @@ -59,13 +59,44 @@ function compileWhen(when) { const targetType = when.file_type; guards.push((diag) => { if (!diag.file) return false; - const classified = classifyFileType(diag.file); - return classified === targetType; + return classifyFileType(diag.file) === targetType; + }); + } + + if (when.has_callers != null) { + const want = !!when.has_callers; + guards.push((diag, facts) => { + if (!facts?.graph || !diag.file) return !want; + return (callerCount(facts.graph, diag.file) > 0) === want; + }); + } + + if (when.caller_count_gte != null) { + const min = Number(when.caller_count_gte); + guards.push((diag, facts) => { + if (!facts?.graph || !diag.file) return false; + return callerCount(facts.graph, diag.file) >= min; + }); + } + + if (when.has_params != null) { + const want = !!when.has_params; + guards.push((diag, facts) => { + if (!facts?.graph || !diag.file) return !want; + return hasDocParams(facts.graph, diag.file) === want; + }); + } + + if (when.is_orphan != null) { + const want = !!when.is_orphan; + guards.push((diag, facts) => { + if (!facts?.graph || !diag.file) return !want; + return isOrphan(facts.graph, diag.file) === want; }); } if (guards.length === 0) return () => true; - return (diag) => guards.every(g => g(diag)); + return (diag, facts) => guards.every(g => g(diag, facts)); } function compileApply(id, apply) { @@ -178,19 +209,6 @@ export function listPromotedRules(projectDir) { // ── Internal helpers ──────────────────────────────────────────────────────── -function classifyFileType(filePath) { - if (!filePath) return 'unknown'; - if (filePath.startsWith('app/views/pages/')) return 'page'; - if (filePath.startsWith('app/views/partials/')) return 'partial'; - if (filePath.startsWith('app/views/layouts/')) return 'layout'; - if (filePath.startsWith('app/lib/commands/')) return 'command'; - if (filePath.startsWith('app/lib/queries/')) return 'query'; - if (filePath.startsWith('app/graphql/')) return 'graphql'; - if (filePath.startsWith('app/schema/')) return 'schema'; - if (filePath.startsWith('modules/')) return 'module'; - return 'unknown'; -} - function globToRegex(glob) { const escaped = glob .replace(/[.+^${}()|[\]\\]/g, '\\$&') diff --git a/src/core/rules/queries.js b/src/core/rules/queries.js index 6b4189e..b504a76 100644 --- a/src/core/rules/queries.js +++ b/src/core/rules/queries.js @@ -80,6 +80,35 @@ export function classifyPath(partialName) { return { type: 'partial', path: `app/views/partials/${partialName}.liquid` }; } +export function callerCount(graph, filePath) { + if (!graph || !filePath) return 0; + return graph.referencedBy(filePath).length; +} + +export function isOrphan(graph, filePath) { + if (!graph || !filePath) return false; + return graph.hasNode(filePath) && graph.referencedBy(filePath).length === 0; +} + +export function hasDocParams(graph, filePath) { + if (!graph || !filePath) return false; + const node = graph.nodeByPath(filePath); + return Array.isArray(node?.params) && node.params.length > 0; +} + +export function classifyFileType(filePath) { + if (!filePath) return 'unknown'; + if (filePath.startsWith('app/views/pages/')) return 'page'; + if (filePath.startsWith('app/views/partials/')) return 'partial'; + if (filePath.startsWith('app/views/layouts/')) return 'layout'; + if (filePath.startsWith('app/lib/commands/')) return 'command'; + if (filePath.startsWith('app/lib/queries/')) return 'query'; + if (filePath.startsWith('app/graphql/')) return 'graphql'; + if (filePath.startsWith('app/schema/')) return 'schema'; + if (filePath.startsWith('modules/')) return 'module'; + return 'unknown'; +} + function levenshtein(a, b) { if (a === b) return 0; if (a.length === 0) return b.length; diff --git a/src/core/session-events.js b/src/core/session-events.js index 8aa8f92..a0dfb32 100644 --- a/src/core/session-events.js +++ b/src/core/session-events.js @@ -117,6 +117,7 @@ const ValidatorEmitPayload = z.object({ new_text_hash: z.string(), kind: z.string(), })).default([]), + params: z.record(z.string(), z.string()).optional(), }); const LogPayload = z.object({ diff --git a/src/core/translation-validator.js b/src/core/translation-validator.js new file mode 100644 index 0000000..5dc56e9 --- /dev/null +++ b/src/core/translation-validator.js @@ -0,0 +1,172 @@ +/** + * platformOS translation YAML validator. + * + * Validates `app/translations/*.yml` files for the structural invariant the + * LSP's TranslationKeyExists check silently depends on: the document MUST be + * keyed by locale at the top level. A file written as + * + * app: + * contact_form: + * title: "..." + * + * parses fine and the LSP won't yell, but `{{ 'app.contact_form.title' | t }}` + * will never resolve — `translation-index.js` strips the top-level key assuming + * it's a locale, so the usable key becomes `contact_form.title` (wrong) instead + * of `app.contact_form.title`. The fix is to wrap the tree in the file's + * locale: + * + * en: + * app: + * contact_form: + * title: "..." + * + * This validator catches the missing-locale-wrapper case up front so the agent + * never ships a translation file that silently fails lookup at runtime. + */ + +import yaml from 'js-yaml'; +import { basename } from 'node:path'; + +// ISO 639-1 two-letter language codes (full list). A looser pattern like +// /^[a-z]{2,3}$/ would false-positive on plain English words such as `app` or +// `ecommerce` — exactly the tokens an agent is tempted to put at the root. +// Pair with an optional ISO 3166-1 region (pt-BR, zh-CN). +const ISO_639_1 = new Set([ + 'aa','ab','ae','af','ak','am','an','ar','as','av','ay','az', + 'ba','be','bg','bh','bi','bm','bn','bo','br','bs', + 'ca','ce','ch','co','cr','cs','cu','cv','cy', + 'da','de','dv','dz', + 'ee','el','en','eo','es','et','eu', + 'fa','ff','fi','fj','fo','fr','fy', + 'ga','gd','gl','gn','gu','gv', + 'ha','he','hi','ho','hr','ht','hu','hy','hz', + 'ia','id','ie','ig','ii','ik','io','is','it','iu', + 'ja','jv', + 'ka','kg','ki','kj','kk','kl','km','kn','ko','kr','ks','ku','kv','kw','ky', + 'la','lb','lg','li','ln','lo','lt','lu','lv', + 'mg','mh','mi','mk','ml','mn','mr','ms','mt','my', + 'na','nb','nd','ne','ng','nl','nn','no','nr','nv','ny', + 'oc','oj','om','or','os', + 'pa','pi','pl','ps','pt', + 'qu', + 'rm','rn','ro','ru','rw', + 'sa','sc','sd','se','sg','si','sk','sl','sm','sn','so','sq','sr','ss','st','su','sv','sw', + 'ta','te','tg','th','ti','tk','tl','tn','to','tr','ts','tt','tw','ty', + 'ug','uk','ur','uz', + 've','vi','vo', + 'wa','wo', + 'xh', + 'yi','yo', + 'za','zh','zu', +]); + +const REGION_RE = /^[A-Z]{2}$/; + +function isLocaleKey(key) { + if (typeof key !== 'string') return false; + const [lang, region, ...rest] = key.split('-'); + if (rest.length > 0) return false; + if (!ISO_639_1.has(lang)) return false; + if (region !== undefined && !REGION_RE.test(region)) return false; + return true; +} + +/** + * Validate a platformOS translation YAML file. + * + * @param {string} content — Raw YAML content + * @param {string} filePath — File path, used for filename-vs-locale check + * @returns {{ errors: Array, warnings: Array }} + */ +export function validateTranslationYaml(content, filePath) { + const errors = []; + const warnings = []; + + if (typeof content !== 'string' || content.trim() === '') return { errors, warnings }; + + let doc; + try { + doc = yaml.load(content); + } catch (e) { + errors.push({ + check: 'pos-supervisor:TranslationYAML', + severity: 'error', + message: `Invalid YAML syntax: ${e.reason || e.message}`, + line: e.mark?.line ?? 0, + column: e.mark?.column ?? 0, + }); + return { errors, warnings }; + } + + if (doc === null || doc === undefined) return { errors, warnings }; + + if (typeof doc !== 'object' || Array.isArray(doc)) { + errors.push({ + check: 'pos-supervisor:TranslationStructure', + severity: 'error', + message: 'Translation file must be a YAML object keyed by locale (e.g. `en:`, `de:`, `pt-BR:`).', + line: 0, + column: 0, + }); + return { errors, warnings }; + } + + const topKeys = Object.keys(doc); + if (topKeys.length === 0) return { errors, warnings }; + + const localeFromFilename = basename(filePath).replace(/\.ya?ml$/, ''); + const expectedLocale = isLocaleKey(localeFromFilename) ? localeFromFilename : 'en'; + + const nonLocaleKeys = topKeys.filter(k => !isLocaleKey(k)); + + // Case 1: zero top-level locale keys — the whole tree is wrongly un-wrapped. + // This is the common agent mistake (no `en:` at the top). Error, not warning, + // because the file will silently fail `| t` lookup in Liquid. + if (nonLocaleKeys.length === topKeys.length) { + const preview = topKeys.slice(0, 3).join(', '); + errors.push({ + check: 'pos-supervisor:TranslationMissingLocaleKey', + severity: 'error', + message: + `Translation file has no top-level locale key. Top-level keys found: ${preview}` + + `${topKeys.length > 3 ? ` (+${topKeys.length - 3} more)` : ''}. ` + + `Wrap the entire tree in the file's locale (e.g. \`${expectedLocale}:\`) — ` + + `platformOS indexes translations by locale at the root. Without this wrapper, ` + + `\`{{ 'key' | t }}\` lookups will silently fail even though the file parses.`, + line: findKeyLine(content, topKeys[0]), + column: 0, + }); + return { errors, warnings }; + } + + // Case 2: mixed locale and non-locale top-level keys. The non-locale keys + // are orphaned translations — they won't be found by any locale. Warn per + // stray key so the agent can either move them under a locale or remove them. + for (const key of nonLocaleKeys) { + warnings.push({ + check: 'pos-supervisor:TranslationStrayTopKey', + severity: 'warning', + message: + `Top-level key \`${key}\` is not a locale code and will not be indexed — ` + + `platformOS only reads keys under locale roots (\`en:\`, \`de:\`, etc.). ` + + `Move \`${key}\` under the correct locale, or rename it to a locale code.`, + line: findKeyLine(content, key), + column: 0, + }); + } + + return { errors, warnings }; +} + +function findKeyLine(content, key) { + const lines = content.split('\n'); + const re = new RegExp(`^${escapeRegex(key)}:`); + for (let i = 0; i < lines.length; i++) { + if (re.test(lines[i])) return i; + } + return 0; +} + +function escapeRegex(s) { + return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} diff --git a/src/dashboard.js b/src/dashboard.js index 9d7b9c9..5199762 100644 --- a/src/dashboard.js +++ b/src/dashboard.js @@ -88,6 +88,16 @@ export function buildDashboardHtml() { .stat-pill .label { color: var(--muted); text-transform: uppercase; } .stat-pill .value { color: var(--text); font-weight: bold; } + .engine-toggle { display: flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; } + .engine-toggle .et-track { position: relative; width: 32px; height: 16px; border-radius: 8px; background: var(--border); transition: background 0.2s; } + .engine-toggle .et-track.on { background: var(--green); } + .engine-toggle .et-knob { position: absolute; top: 2px; left: 2px; width: 12px; height: 12px; border-radius: 50%; background: var(--bg); transition: left 0.2s; } + .engine-toggle .et-track.on .et-knob { left: 18px; } + .engine-toggle .et-label { font-size: 10px; font-weight: bold; text-transform: uppercase; min-width: 48px; } + .engine-toggle .et-label.adaptive { color: var(--green); } + .engine-toggle .et-label.static { color: var(--muted); } + .engine-toggle.switching .et-track { opacity: 0.5; pointer-events: none; } + .dot { width: 8px; height: 8px; display: inline-block; flex-shrink: 0; } .dot.green { background: var(--green); } .dot.red { background: var(--red); } @@ -531,6 +541,9 @@ export function buildDashboardHtml() { .an-legend code { background: var(--bg); padding: 1px 4px; border: 1px solid var(--border); font-size: 10px; color: var(--text); } .an-legend b { color: var(--text); } .an-empty { color: var(--muted); font-size: 12px; padding: 12px 0; } + /* Reserve vertical space for panels whose content height varies on load, so + clicking a row doesn't shift everything below. */ + #an-journey, #an-calibration, #an-funnel, #an-heatmap, #an-radar { min-height: 160px; } .an-stats-row { display: flex; gap: 12px; margin-bottom: 20px; flex-wrap: wrap; } .an-stat { background: var(--bg); border: 1px solid var(--border); padding: 10px 16px; min-width: 140px; box-shadow: 2px 2px 0 var(--border); } @@ -928,6 +941,13 @@ export function buildDashboardHtml() {
VER : —
CALLS : 0
ERR : 0
+
+ ENGINE : +
+
+ STATIC +
+
CONNECTING
@@ -1246,7 +1266,15 @@ export function buildDashboardHtml() {
Confidence Calibration
-
Compares predicted confidence (from rule output) against actual resolution rate. Points on the diagonal = perfectly calibrated. Points below = overconfident. Points above = underconfident.
+
+ What this chart shows. Every rule-matched diagnostic carries a predicted confidence (0–100%) — the engine's estimate that the fix will resolve the problem. We bucket all diagnostics by that predicted value (10 buckets: 0-10%, 10-20%, …) and plot one dot per non-empty bucket.
+ X axis — bucket's predicted confidence (mid-point). + Y axis — actual resolution rate observed in that bucket (share of diagnostics in the bucket that disappeared after the agent's next edit). + Dot size — number of samples in the bucket (bigger = more data, more trustworthy). + Dot color — green within 10% of the diagonal, yellow 10–20%, red >20%.
+ How to read it. The dashed diagonal = perfect calibration (predicted = actual). Below the diagonal = overconfident (engine said 80%, reality 40%). Above the diagonal = underconfident (engine said 30%, reality 70%). Hover any dot for exact values and sample count.
+ Data source. GET /api/analytics/calibration?buckets=10 — computed from the analytics DB over every diagnostic with a rule-supplied confidence score. +
No confidence data yet.
@@ -1263,8 +1291,8 @@ export function buildDashboardHtml() {
-
Knowledge Coverage
-
Radar chart showing 5 dimensions of knowledge system health: rule coverage, hint quality, fix adoption, diagnostic freshness, and resolution rate.
+
Knowledge Coverage (Global System Health)
+
Global 5-axis view — not per-check. Each axis is aggregated across every diagnostic the engine has seen: Rule Coverage (% of checks with a rule), Hint Quality (avg resolution rate after a hint fires), Fix Adoption (proposed fixes the agent applied), Rule Match (emitted diagnostics a rule matched), Resolution (emitted diagnostics that disappeared). Larger area = healthier engine overall. For per-check calibration see the scatter plot above.
No coverage data yet.
@@ -1649,6 +1677,10 @@ function initSse() { } else if (['lsp_ready','lsp_crash','lsp_init_failed','lsp_warmed_up'].includes(entry.event)) { fetchStatus(); renderLspLog(); + } else if (entry.event === 'engine_mode_changed' && entry.mode) { + syncEngineToggle(entry.mode); + } else if (entry.event === 'fs_watcher_sync' || entry.event === 'fs_watcher_delete') { + scheduleExplorerRefreshFromFsEvent(); } } catch {} }); @@ -1680,6 +1712,8 @@ async function fetchStatus() { document.getElementById('sb-version').textContent = d.version || '—'; document.getElementById('sb-tools').textContent = d.toolCount ?? '—'; + syncEngineToggle(d.engineMode || 'static'); + startTime = startTime ?? (Date.now() - (d.uptimeMs ?? 0)); sessionStart = sessionStart ?? d.startedAt ?? null; @@ -1718,6 +1752,36 @@ async function fetchStatus() { } catch {} } +// ── Engine mode toggle ──────────────────────────────────────────────────── +function syncEngineToggle(mode) { + var track = document.getElementById('et-track'); + var label = document.getElementById('et-label'); + var toggle = document.getElementById('engine-toggle'); + if (!track || !label) return; + var isAdaptive = mode === 'adaptive'; + track.className = 'et-track' + (isAdaptive ? ' on' : ''); + label.textContent = isAdaptive ? 'ADAPTIVE' : 'STATIC'; + label.className = 'et-label ' + (isAdaptive ? 'adaptive' : 'static'); + toggle.classList.remove('switching'); +} + +document.getElementById('engine-toggle').addEventListener('click', function() { + var toggle = document.getElementById('engine-toggle'); + var label = document.getElementById('et-label'); + if (toggle.classList.contains('switching')) return; + var current = label.textContent === 'ADAPTIVE' ? 'adaptive' : 'static'; + var next = current === 'adaptive' ? 'static' : 'adaptive'; + toggle.classList.add('switching'); + fetch(BASE + '/api/engine/mode', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ mode: next }), + }) + .then(function(r) { return r.json(); }) + .then(function(d) { if (d.mode) syncEngineToggle(d.mode); }) + .catch(function() { toggle.classList.remove('switching'); }); +}); + // ── Bootstrap: load historical logs, then switch to SSE ───────────────── async function fetchInitialLogs() { try { @@ -2971,6 +3035,19 @@ async function fetchExplorerData() { if (btn) { btn.disabled = false; btn.textContent = 'FETCH DATA'; } } +// Debounced quiet refresh triggered by fs_watcher SSE events. +// Only refreshes when explorer data has already been loaded — avoids forcing +// work before the user opens the tab. Coalesces bursts into a single call. +let fsRefreshTimer = null; +function scheduleExplorerRefreshFromFsEvent() { + if (!explorerLoaded) return; + if (fsRefreshTimer) clearTimeout(fsRefreshTimer); + fsRefreshTimer = setTimeout(() => { + fsRefreshTimer = null; + fetchExplorerData(); + }, 500); +} + async function fetchAnalysisData() { const btn = document.getElementById('ht-refresh-btn'); if (btn) { btn.disabled = true; btn.textContent = 'ANALYZING…'; } @@ -4779,6 +4856,7 @@ function renderCalibrationChart(el, data) { var diagLabel = 'perfect calibration'; var legend = '
' + + 'Each dot = one confidence bucket (predicted vs actual resolution).' + ' within 10% of predicted' + ' 10-20% deviation' + ' >20% deviation' @@ -4990,7 +5068,7 @@ function renderRadarChart(el, gaps, funnel) { const areaCls = area > 0.7 ? 'var(--green)' : area > 0.4 ? 'var(--yellow)' : 'var(--red)'; el.innerHTML = '
' - + '

Knowledge Coverage

' + + '

Knowledge Coverage — Global System Health

' + '' + gridHtml + axisHtml + labelHtml + '' @@ -5314,14 +5392,15 @@ async function runLiveConsole() { statusEl.textContent = ''; resultEl.style.display = 'none'; - const filePath = currentLiveFilePath || ('' + ext); + const virtualPaths = { '.liquid': 'app/views/partials/__pos_live_console__.liquid', '.graphql': 'app/graphql/__pos_live_console__.graphql', '.yml': 'app/schema/__pos_live_console__.yml' }; + const filePath = currentLiveFilePath || (virtualPaths[ext] || virtualPaths['.liquid']); const t0 = Date.now(); try { const r = await fetch(BASE + '/call', { method: 'POST', headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ tool: 'validate_code', params: { file_path: filePath, content } }), + body: JSON.stringify({ tool: 'validate_code', params: { file_path: filePath, content, _source: 'dashboard_live' } }), }); const d = await r.json(); const dur = fmtDuration(Date.now() - t0); diff --git a/src/data/hints/TranslationKeyExists.md b/src/data/hints/TranslationKeyExists.md index 205de4e..7897622 100644 --- a/src/data/hints/TranslationKeyExists.md +++ b/src/data/hints/TranslationKeyExists.md @@ -3,6 +3,18 @@ Translation key '{{key}}' not found in translation files. NOTE: If you are creating translation files as part of a multi-file plan, pass pending_translations (from validate_intent) to validate_code — this suppresses TranslationKeyExists for keys that will exist once the plan is written to disk. + +IF Translations show "translation missing" even though the key exists in the YAML file. +Root cause: The YAML file is missing the required top-level language key. + +```yaml +en: + app: + contact_form: + title: "..." +``` + +OTHERWISE: STEP 1 — Check the suggestion field for a typo fix. HAS suggestion (Did you mean '...'?): @@ -19,4 +31,4 @@ STEP 2 — Add the missing translation key. STEP 3 — Apply: '{{key}}' | t MUST NOT: Remove the | t filter or replace translations with hardcoded text to silence this. -MUST NOT: Create a new key if STEP 1 found a suggestion — fix the typo instead. \ No newline at end of file +MUST NOT: Create a new key if STEP 1 found a suggestion — fix the typo instead. diff --git a/src/data/hints/UnrecognizedRenderPartialArguments.md b/src/data/hints/UnrecognizedRenderPartialArguments.md new file mode 100644 index 0000000..aa4755a --- /dev/null +++ b/src/data/hints/UnrecognizedRenderPartialArguments.md @@ -0,0 +1,18 @@ +Argument '{{unrecognized_param}}' passed to '{{partial_name}}' is not declared in its {% doc %} block. + +STEP 1 — Open the partial and read its {% doc %} block. + File: app/views/partials/{{partial_name}}.liquid + Every argument passed must match a declared @param: + @param name {string} — required + @param [name] {string} — optional + +STEP 2 — Choose one fix: + A) Remove the unrecognized argument from the calling tag in THIS file. + The partial does not read it, so passing it is dead data. + B) Add the missing @param to the partial's {% doc %} block. + Use this if the partial should read the value. + C) Rename the argument to match an existing @param. + Use this if the name was a typo. + +MUST NOT: Leave the unrecognized argument in place assuming the partial will figure it out — @param is the contract, undeclared arguments are silently dropped. +MUST NOT: Delete all @param declarations to silence the check — that removes the interface documentation other callers rely on. diff --git a/src/data/references/pages/gotchas.md b/src/data/references/pages/gotchas.md index 7034930..224062d 100644 --- a/src/data/references/pages/gotchas.md +++ b/src/data/references/pages/gotchas.md @@ -102,7 +102,7 @@ The `function` tag also supports these forms: `{% function data['product'] = 'pr ### Root page (`/`) — omit the slug entirely -**Cause:** Setting `slug: /` or `slug: ""` in front matter for the home page, then getting an InvalidSlug warning. +**Cause:** Setting `slug: /` or `slug: ""` or `slug: index` in front matter for the home page, then getting an InvalidSlug warning. **Solution:** For the home page (root `/`), do not set a slug at all. A page at `app/views/pages/index.html.liquid` serves `/` by default — no front matter slug is needed. diff --git a/src/data/resources/platformos-development-guide-full.md b/src/data/resources/platformos-development-guide-full.md new file mode 100644 index 0000000..4cbe916 --- /dev/null +++ b/src/data/resources/platformos-development-guide-full.md @@ -0,0 +1,3154 @@ +# platformOS Development Guide for LLM Agents + +> **Essential Knowledge Base for AI Coding Agents** +> Version: 2025-2026 | Last Updated: April 2026 +> Source: [platformOS Documentation](https://documentation.platformos.com/) + +--- + +## Table of Contents + +1. [Introduction & Architecture](#1-introduction--architecture) +2. [Directory Structure](#2-directory-structure) +3. [Core Concepts](#3-core-concepts) +4. [Pages & Layouts](#4-pages--layouts) +5. [Records & Tables](#5-records--tables) +6. [Properties](#6-properties) +7. [Forms](#7-forms) +8. [Liquid Templating](#8-liquid-templating) +9. [GraphQL API](#9-graphql-api) +10. [Users & Authentication](#10-users--authentication) +11. [Authorization Policies](#11-authorization-policies) +12. [Modules](#12-modules) +13. [Background Jobs](#13-background-jobs) +14. [Notifications](#14-notifications) +15. [Assets & Uploads](#15-assets--uploads) +16. [Best Practices](#16-best-practices) +17. [Common Gotchas & Pitfalls](#17-common-gotchas--pitfalls) +18. [Performance Optimization](#18-performance-optimization) +19. [Testing & CI/CD](#19-testing--cicd) +20. [System Limitations](#20-system-limitations) +21. [Data Import/Export](#22-data-importexport) +22. [Quick Reference](#23-quick-reference) +23. [Translations](#24-translations) +24. [Activity Feeds](#25-activity-feeds) +25. [JSON Documents](#26-json-documents) +26. [AI Embeddings](#27-ai-embeddings) +27. [Migrations](#28-migrations) + +--- + +## 1. Introduction & Architecture + +### What is platformOS? + +platformOS is a **model-based application development platform** (PaaS) that enables developers to build web applications, APIs, and digital products without managing infrastructure. It combines: + +- **Liquid templating** for views +- **GraphQL** for data queries and mutations +- **YAML configuration** for schema definition +- **Background job processing** for async operations +- **Built-in authentication & authorization** + +### Key Architectural Principles + +| Principle | Description | +|-----------|-------------| +| **Convention over Configuration** | File locations determine behavior | +| **Git-based Workflow** | Version control everything | +| **Multi-tenancy** | Multiple instances per codebase | +| **Serverless Backend** | No server management required | +| **Edge Caching** | Built-in CDN for performance | + +### Development Workflow + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Local │───▶│ Test │───▶│ Staging │───▶│ Production │ +│ Development │ │ Instance │ │ Instance │ │ Instance │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ │ + └──────────────────┴──────────────────┴──────────────────┘ + pos-cli deploy +``` + +--- + +## 2. Directory Structure + +### Required Directory Layout + +``` +project-root/ +├── app/ # Main application code +│ ├── assets/ # Static files (CSS, JS, images) +│ ├── authorization_policies/ # Access control rules +│ ├── emails/ # Email notification templates +│ ├── api_calls/ # API call notifications +│ ├── smses/ # SMS notification templates +│ ├── forms/ # Form configurations +│ ├── graphql/ # GraphQL query files +│ ├── migrations/ # Data migration scripts +│ ├── schema/ # Table definitions (YAML) +│ ├── views/ +│ │ ├── layouts/ # Page layouts +│ │ ├── pages/ # Page definitions +│ │ └── partials/ # Reusable Liquid snippets +│ ├── config.yml # App configuration +│ └── user.yml # User property definitions +├── modules/ # External modules +│ └── MODULE_NAME/ +│ ├── public/ # Publicly accessible files +│ └── private/ # IP-protected files +└── .pos # pos-cli configuration +``` + +### Critical File Locations + +| Component | Required Path | Extension | +|-----------|---------------|-----------| +| Pages | `app/views/pages/` | `.liquid` | +| Layouts | `app/views/layouts/` | `.liquid` | +| Partials | `app/views/partials/` | `.liquid` | +| Tables | `app/schema/` | `.yml` | +| Forms | `app/forms/` | `.liquid` | +| GraphQL | `app/graphql/` | `.graphql` | +| Assets | `app/assets/` | any | + +### Configuration Files + +**`.pos` (pos-cli config):** +```yaml +staging: + url: https://staging.example.com + email: dev@example.com +production: + url: https://www.example.com + email: dev@example.com +``` + +**`app/config.yml`:** +```yaml +# Modules that can be deleted during deploy +modules_that_allow_delete_on_deploy: + - my_module + +# Other app-level configuration +``` + +--- + +## 3. Core Concepts + +### The platformOS Data Flow + +``` +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Client │───▶│ Router │───▶│ Liquid │───▶│ GraphQL │ +│ Request │ │ (Page) │ │ Template │ │ Query │ +└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ + │ + ┌────▼─────┐ + │ Database │ + │ (Record) │ + └──────────┘ +``` + +### Key Terminology + +| Term | Definition | +|------|------------| +| **Instance** | A deployed environment (staging, production) | +| **Table** | Schema definition for data objects | +| **Record** | Individual data object instance | +| **Property** | Field/column definition | +| **Page** | Route handler + view template | +| **Layout** | Wrapper template for pages | +| **Partial** | Reusable template snippet | +| **Form** | Configuration for data submission | +| **Authorization Policy** | Access control rule | + +--- + +## 4. Pages & Layouts + +### Page Configuration + +Pages are defined in `app/views/pages/` with `.liquid` extension. URL path is derived from file location unless `slug` is specified. + +**File:** `app/views/pages/blog/post.html.liquid` +```liquid +--- +slug: blog/:slug +layout: blog_layout +converter: markdown +authorization_policies: + - valid_user_policy +--- + +

{{ context.params.slug }}

+

Author: {{ context.current_user.email }}

+``` + +### Page Configuration Options + +| Option | Type | Description | +|--------|------|-------------| +| `slug` | String | URL pattern (e.g., `products/:id`) | +| `layout` | String | Layout template name | +| `converter` | String | `markdown`, `textile` | +| `authorization_policies` | Array | Policies to check | +| `response_headers` | Hash | Custom HTTP headers | +| `method` | String | HTTP method restriction | + +### Dynamic URL Parameters + +```yaml +# Required parameter +slug: products/:id +# Access: context.params.id + +# Optional parameter +slug: search(/:country)(/:city) +# Matches: /search, /search/USA, /search/USA/NYC + +# Wildcard parameter +slug: docs/*path +# Access: context.params.path (contains full remaining path) + +# Optional wildcard +slug: docs(/*path) +# Matches: /docs and /docs/anything/here +``` + +### Layouts + +**File:** `app/views/layouts/application.liquid` +```liquid + + + + {{ page_title | default: 'My App' }} + {{ content_for_head }} + + + {% render 'header' %} + +
+ {{ content_for_layout }} +
+ + {% render 'footer' %} + + +``` + +**Key Layout Variables:** +- `content_for_layout` - Page content injection point +- `content_for_head` - Head content (meta tags, styles) + +### Context Object (Complete Reference) + +The `context` object is the **only predefined global object** in platformOS Liquid. It is available in pages, partials, layouts, and notifications. + +#### Authentication & User + +```liquid +{{ context.current_user }} # Current user object or null +{{ context.current_user.id }} # User UUID +{{ context.current_user.email }} # User email +{{ context.current_user.first_name }}# First name +{{ context.current_user.last_name }} # Last name +{{ context.current_user.slug }} # User slug +{{ context.current_user.properties }}# Custom properties hash +``` + +#### Request Data + +```liquid +{{ context.params }} # URL params + query string + form data +{{ context.params.id }} # Named route parameter +{{ context.params.page }} # Query string parameter +{{ context.headers }} # HTTP headers hash +{{ context.headers.REQUEST_METHOD }} # GET, POST, etc. +{{ context.headers.PATH_INFO }} # Request path +{{ context.cookies }} # Cookies hash +{{ context.session }} # Session data hash +``` + +#### Security + +```liquid +{{ context.authenticity_token }} # CSRF token for forms +{{ context.constants }} # Sensitive config (API keys, secrets) +``` + +**Accessing Constants:** +```liquid +{{ context.constants.STRIPE_API_KEY }} +{{ context.constants.SENDGRID_API_KEY }} +``` + +Set constants via GraphQL: +```graphql +mutation { + constant_set(name: "STRIPE_API_KEY", value: "sk_live_...") +} +``` + +#### Device & Environment + +```liquid +{{ context.device }} # Device detection hash +{{ context.device.device_type }} # desktop, smartphone, tablet, etc. +{{ context.device.browser }} # Browser name +{{ context.device.os }} # Operating system +{{ context.environment }} # "staging" or "production" +``` + +#### Flash Messages + +```liquid +{{ context.flash }} # Flash messages hash +{{ context.flash.notice }} # Success message +{{ context.flash.alert }} # Error message +``` + +**Available Device Types:** +- `desktop` +- `smartphone` +- `tablet` +- `console` +- `portable media player` +- `tv` +- `car browser` +- `camera` + +**Available HTTP Headers:** +- `SERVER_NAME` +- `REQUEST_METHOD` +- `PATH_INFO` +- `REQUEST_URI` +- `HTTP_AUTHORIZATION` + +--- + +## 5. Records & Tables + +### Defining Tables + +Tables define data structure in `app/schema/` as YAML files. + +**File:** `app/schema/blog_post.yml` +```yaml +name: blog_post +properties: + - name: title + type: string + - name: content + type: text + - name: published_at + type: datetime + - name: author_id + type: string + - name: tags + type: array + - name: metadata + type: jsonb +``` + +### Property Types Reference + +| Type | Description | Liquid Equivalent | +|------|-------------|-------------------| +| `string` | Short text (255 chars) | String | +| `text` | Long text | String | +| `integer` | Whole numbers | Integer | +| `float` | Decimal numbers | Float | +| `boolean` | true/false | Boolean | +| `date` | Date only | Date | +| `datetime` | Date + Time | DateTime | +| `array` | List of values | Array | +| `jsonb` | JSON data | Hash | +| `geojson` | Geographic data | GeoJSON Object | +| `upload` | File attachment | Upload Object | + +### Record Lifecycle + +``` +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Create │───▶│ Read │───▶│ Update │───▶│ Delete │ +│ record │ │ record │ │ record │ │ record │ +└─────────┘ └─────────┘ └─────────┘ └─────────┘ + │ │ │ │ + GraphQL GraphQL GraphQL GraphQL + mutation query mutation mutation +``` + +### Creating Records via GraphQL + +**File:** `app/graphql/records/create_blog_post.graphql` +```graphql +mutation create_blog_post( + $title: String! + $content: String! + $author_id: String! +) { + record_create( + record: { + table: "blog_post" + properties: [ + { name: "title", value: $title } + { name: "content", value: $content } + { name: "author_id", value: $author_id } + ] + } + ) { + id + created_at + properties + } +} +``` + +### Querying Records + +**File:** `app/graphql/records/get_blog_posts.graphql` +```graphql +query get_blog_posts( + $limit: Int = 10 + $published: Boolean = true +) { + records( + per_page: $limit + filter: { + table: { value: "blog_post" } + properties: [ + { name: "published", value_boolean: $published } + ] + } + sort: [{ created_at: { order: DESC } }] + ) { + results { + id + created_at + properties + } + total_entries + total_pages + } +} +``` + +### CRUD Operations Summary + +| Operation | GraphQL | Example | +|-----------|---------|---------| +| Create | `record_create` | Create new record | +| Read | `records`, `record` | Query records | +| Update | `record_update` | Modify existing | +| Delete | `record_delete` | Soft/hard delete | + +--- + +## 6. Properties + +### Property Configuration + +Properties are defined in Table YAML files: + +```yaml +properties: + - name: status + type: string + default: draft + + - name: view_count + type: integer + default: 0 + + - name: settings + type: jsonb + + - name: tags + type: array +``` + +### Array Properties + +Arrays can store multiple values of any type: + +```yaml +properties: + - name: tags + type: array +``` + +**GraphQL mutation:** +```graphql +mutation { + record_create( + record: { + table: "blog_post" + properties: [ + { name: "tags", value_array: ["tech", "news", "featured"] } + ] + } + ) { + id + } +} +``` + +### JSONB Properties + +Store complex nested data: + +```yaml +properties: + - name: metadata + type: jsonb +``` + +**GraphQL mutation:** +```graphql +mutation { + record_create( + record: { + table: "blog_post" + properties: [ + { + name: "metadata", + value_json: "{\"seo_title\": \"My Post\", \"keywords\": [\"a\", \"b\"]}" + } + ] + } + ) { + id + } +} +``` + +### Upload Properties + +Handle file uploads: + +```yaml +properties: + - name: avatar + type: upload +``` + +**In forms:** +```liquid +{% form %} + + +{% endform %} +``` + +--- + +## 7. Forms + +### Form Structure + +Forms have two sections: YAML configuration + Liquid implementation. + +**File:** `app/forms/contact_form.liquid` +```liquid +--- +name: contact_form +resource: contact_message +resource_owner: anyone +redirect_to: /contact/thank-you +flash_notice: Message sent successfully! +fields: + properties: + name: + validation: + presence: true + email: + validation: + presence: true + email: true + message: + validation: + presence: true + length: + minimum: 10 +email_notifications: + - contact_notification +authorization_policies: + - not_spam_policy +--- + +{% form %} +
+ + + {% if form.fields.properties.name.errors %} + {{ form.fields.properties.name.errors }} + {% endif %} +
+ +
+ + +
+ +
+ + +
+ + +{% endform %} +``` + +### Form Configuration Options + +| Option | Description | +|--------|-------------| +| `name` | Unique form identifier | +| `resource` | Associated table name | +| `resource_owner` | `anyone`, `self`, `anyone_with_token` | +| `redirect_to` | URL after successful submission | +| `flash_notice` | Success message | +| `flash_alert` | Error message | +| `fields` | Field definitions and validation | +| `email_notifications` | Emails to send | +| `api_call_notifications` | API calls to make | +| `callback_actions` | Synchronous Liquid code | +| `async_callback_actions` | Background job code | +| `authorization_policies` | Access control | +| `default_payload` | JSON payload to merge | + +### Validation Options + +```yaml +fields: + properties: + email: + validation: + presence: + message: Email is required + email: true + uniqueness: + message: Email already exists + password: + validation: + length: + minimum: 8 + message: Password too short + confirmation: true # Requires password_confirmation field + age: + validation: + numericality: + greater_than: 0 + less_than: 150 + website: + validation: + url: true +``` + +### Rendering Forms in Pages + +```liquid +--- +slug: contact +--- + +

Contact Us

+ +{% render_form 'contact_form' %} + + +
+ {% render_form 'contact_form', class: 'contact-form' %} +
+``` + +### Form Object Structure + +```liquid +{{ form.fields.properties.FIELD_NAME.name }} # Input name attribute +{{ form.fields.properties.FIELD_NAME.value }} # Current value +{{ form.fields.properties.FIELD_NAME.errors }} # Validation errors +{{ form.errors }} # All form errors +{{ form.valid? }} # Boolean validation state +``` + +--- + +## 8. Liquid Templating + +### platformOS Liquid Tags + +#### Query Tag (GraphQL Execution) + +```liquid +{% graphql my_query = 'get_blog_posts', limit: 10 %} + +{% for post in my_query.records.results %} +

{{ post.properties.title }}

+{% endfor %} +``` + +#### Background Tag (Async Jobs) + +```liquid +{% background job_id = 'send_email', delay: 0.5, priority: 'high', max_attempts: 3 %} + {% graphql result = 'send_notification', user_id: user_id %} + {% log result %} +{% endbackground %} +``` + +**Background Options:** +- `delay`: Minutes to delay (default: 0) +- `priority`: `low`, `default`, `high` +- `max_attempts`: 1-5 retries (default: 1) +- `source_name`: Job identifier label + +**CRITICAL:** Variables must be explicitly passed to background: +```liquid +{% background data: my_data, user_id: user.id %} + {{ data }} {# Available #} + {{ my_data }} {# NOT available - wasn't passed #} +{% endbackground %} +``` + +#### Include/Render Tags + +```liquid +{# Include with local variables #} +{% include 'header', title: 'My Page', show_nav: true %} + +{# Render (preferred - isolated scope) #} +{% render 'product_card', product: product %} + +{# Render with collection #} +{% render 'product_card' for products as product %} +``` + +#### Function Tag + +```liquid +{% function my_result = 'helpers/calculate_total', items: cart_items %} + +{# In app/views/partials/helpers/calculate_total.liquid #} +{% return items | sum: 'price' %} +``` + +#### Parse JSON Tag + +```liquid +{% parse_json my_data %} + { + "name": "John", + "items": [1, 2, 3] + } +{% endparse_json %} + +{{ my_data.name }} {# John #} +``` + +#### Cache Tag + +Cache expensive operations to improve performance: + +```liquid +{% cache key: 'sidebar_categories', expire: 3600 %} + {% graphql categories = 'get_categories' %} + {% for category in categories.records.results %} + {{ category.properties.name }} + {% endfor %} +{% endcache %} +``` + +**Cache Options:** +- `key` - Unique cache identifier +- `expire` - Cache lifetime in seconds +- `if` - Conditional caching + +```liquid +{% cache key: 'user_stats', expire: 300, if: context.current_user %} + {# Only cache for logged-in users #} +{% endcache %} +``` + +#### Log Tag + +Debug by logging to instance logs: + +```liquid +{% log 'Debug message' %} +{% log user_id: user.id, action: 'purchase' %} +{% log my_variable %} +``` + +View logs with: `pos-cli logs staging` + +#### Content For Tag + +Inject content into layouts: + +```liquid +{# In page #} +{% content_for 'head' %} + + +{% endcontent_for %} + +{# In layout #} + + {{ content_for_head }} + +``` + +#### Yield Tag + +Define content blocks in layouts: + +```liquid +{# In layout #} + + +{# In page #} +{% content_for 'sidebar' %} +
+

Related Links

+
+{% endcontent_for %} +``` + +#### Return Tag + +Return values from function partials: + +```liquid +{# app/views/partials/calculate_tax.liquid #} +{% assign tax = amount | times: 0.2 %} +{% return tax %} + +{# Usage #} +{% function tax_amount = 'calculate_tax', amount: 100 %} +Tax: {{ tax_amount }} +``` + +#### Raw Tag + +Prevent Liquid from processing content: + +```liquid +{% raw %} + {{ this will not be processed }} + {% if true %}neither will this{% endif %} +{% endraw %} +``` + +#### Liquid Tag (New Syntax) + +Use the new Liquid tag syntax for cleaner code: + +```liquid +{% liquid + assign user = context.current_user + if user + echo 'Hello, ' | append: user.first_name + else + echo 'Hello, Guest' + endif +%} +``` + +### Complete platformOS Tag Reference + +| Tag | Purpose | +|-----|---------| +| `{% graphql %}` | Execute GraphQL queries | +| `{% background %}` | Run async background jobs | +| `{% form %}` | Render form with CSRF protection | +| `{% render_form %}` | Include a form by name | +| `{% include %}` | Include partial (deprecated, use render) | +| `{% render %}` | Render partial with isolated scope | +| `{% function %}` | Call function partial with return value | +| `{% parse_json %}` | Parse JSON string to object | +| `{% cache %}` | Cache content fragment | +| `{% log %}` | Log to instance logs | +| `{% content_for %}` | Define content for layout blocks | +| `{% yield %}` | Insert content block in layout | +| `{% return %}` | Return value from function | +| `{% raw %}` | Disable Liquid processing | +| `{% liquid %}` | New multi-line Liquid syntax | + +### platformOS Liquid Filters + +#### Array Filters + +```liquid +{# Add to array #} +{% assign new_array = old_array | add_to_array: 'new_item' %} + +{# Compact - remove nil values #} +{% assign clean = array | compact %} + +{# Group by property #} +{% assign grouped = products | group_by: 'category' %} + +{# Map/extract property #} +{% assign names = users | map: 'name' %} + +{# Sort by property #} +{% assign sorted = products | sort_by: 'price' %} + +{# Sum array values #} +{{ order_items | sum: 'total' }} + +{# Find unique values #} +{% assign unique_tags = all_tags | uniq %} +``` + +#### Date/Time Filters + +```liquid +{{ 'now' | to_time }} +{{ '2024-01-15' | to_time | add_to_time: 1, 'week' }} +{{ 'now' | strftime: '%Y-%m-%d %H:%M' }} +{{ post.created_at | time_ago_in_words }} +``` + +#### Hash/Object Filters + +```liquid +{# Merge hashes #} +{% assign combined = defaults | hash_merge: overrides %} + +{# Get keys #} +{% assign keys = config | hash_keys %} + +{# Get values #} +{% assign values = config | hash_values %} + +{# Deep clone #} +{% assign copy = original | deep_clone %} +``` + +#### URL Filters + +```liquid +{{ 'style.css' | asset_url }} +{{ 'photo.jpg' | asset_url | img_tag: 'Photo' }} +{{ user.avatar | default: 'default.png' | asset_url }} +``` + +#### String Filters + +```liquid +{{ text | strip_html }} +{{ text | truncate: 100 }} +{{ text | truncatewords: 20 }} +{{ text | url_encode }} +{{ text | url_decode }} +{{ text | md5 }} +{{ text | sha1 }} +{{ text | hmac_sha256: secret_key }} +{{ text | base64_encode }} +{{ text | base64_decode }} +{{ text | html_safe }} {# Mark as safe HTML #} +{{ text | sanitize }} {# Sanitize HTML input #} +{{ text | escape_javascript }} {# Escape for JS #} +{{ text | json }} {# Convert to JSON #} +``` + +#### Number/Currency Filters + +```liquid +{{ 1234.5 | round }} {# 1235 #} +{{ 1234.5 | round: 1 }} {# 1234.5 #} +{{ 1234.5 | ceil }} {# 1235 #} +{{ 1234.5 | floor }} {# 1234 #} +{{ 19.99 | amount_to_fractional: 'USD' }} {# 1999 (cents) #} +{{ 1999 | fractional_to_amount: 'USD' }} {# 19.99 #} +{{ 1234567 | format_number: 'en' }} {# 1,234,567 #} +``` + +#### Encoding/Encryption Filters + +```liquid +{{ 'text' | base64_encode }} +{{ 'ZW5jb2RlZA==' | base64_decode }} +{{ 'text' | md5 }} +{{ 'text' | sha1 }} +{{ 'text' | hmac_sha256: secret_key }} +{{ 'text' | encrypt: key, algorithm: 'aes-256-gcm' }} +{{ 'encrypted' | decrypt: key, algorithm: 'aes-256-gcm' }} +``` + +**Supported Encryption Algorithms:** +- `aes-128-cbc`, `aes-192-cbc`, `aes-256-cbc` +- `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm` +- `aes-128-ctr`, `aes-192-ctr`, `aes-256-ctr` +- And many more... + +#### URL/Link Filters + +```liquid +{{ 'style.css' | asset_url }} +{{ 'photo.jpg' | asset_url | img_tag: 'Alt text' }} +{{ 'photo.jpg' | asset_url | img_tag: 'Alt', 'class-name' }} +{{ '/path' | link_to: 'Click here' }} +{{ 'page' | app_url }} {# Generate app URL #} +``` + +#### Debug/Development Filters + +```liquid +{{ variable | debug }} {# Debug output #} +{{ variable | inspect }} {# Ruby-style inspect #} +{{ 'code' | time_diff }} {# Measure execution time #} +``` + +### Complete platformOS Filter Reference + +| Category | Filters | +|----------|---------| +| **Array** | `add_to_array`, `compact`, `group_by`, `map`, `sort_by`, `sum`, `uniq`, `flatten`, `shuffle`, `rotate`, `in_groups_of` | +| **Date** | `to_time`, `add_to_time`, `strftime`, `time_ago_in_words`, `date_add` | +| **Hash** | `hash_merge`, `hash_keys`, `hash_values`, `deep_clone` | +| **String** | `strip_html`, `truncate`, `truncatewords`, `url_encode`, `md5`, `sha1`, `hmac_sha256`, `base64_encode`, `sanitize`, `html_safe` | +| **Number** | `round`, `ceil`, `floor`, `format_number`, `amount_to_fractional`, `fractional_to_amount` | +| **URL** | `asset_url`, `img_tag`, `link_to`, `app_url` | +| **JSON** | `json`, `parse_json` | +| **Debug** | `debug`, `inspect`, `time_diff` | + +### Whitespace Control + +```liquid +{# Use hyphens to control whitespace #} +{%- if condition -%} + No extra whitespace +{%- endif -%} + +{# Output whitespace control #} +{{- variable -}} +``` + +--- + +## 9. GraphQL API + +### Query Structure + +All GraphQL queries are stored in `app/graphql/` with `.graphql` extension. + +### Record Queries + +**List Records:** +```graphql +query list_products( + $page: Int = 1 + $per_page: Int = 20 + $category: String +) { + records( + per_page: $per_page + page: $page + filter: { + table: { value: "product" } + properties: [ + { name: "category", value: $category } + ] + } + sort: [{ price: { order: ASC } }] + ) { + total_entries + total_pages + has_next_page + has_previous_page + results { + id + created_at + updated_at + deleted_at + type_name + properties + } + } +} +``` + +**Single Record:** +```graphql +query get_product($id: ID!) { + record(id: $id) { + id + properties + } +} +``` + +### Record Mutations + +**Create:** +```graphql +mutation create_product( + $name: String! + $price: Float! +) { + record_create( + record: { + table: "product" + properties: [ + { name: "name", value: $name } + { name: "price", value_float: $price } + ] + } + ) { + id + properties + errors { + message + } + } +} +``` + +**Update:** +```graphql +mutation update_product( + $id: ID! + $name: String +) { + record_update( + id: $id + record: { + properties: [ + { name: "name", value: $name } + ] + } + ) { + id + properties + } +} +``` + +**Delete:** +```graphql +mutation delete_product($id: ID!) { + record_delete(id: $id) { + id + deleted_at + } +} +``` + +### User Queries + +```graphql +# Get current user +query current_user { + current_user { + id + email + created_at + properties + } +} + +# List users +query list_users { + users { + results { + id + email + properties + } + } +} + +# Create user +mutation create_user( + $email: String! + $password: String! +) { + user_create( + user: { + email: $email + password: $password + } + ) { + id + email + } +} +``` + +### Pagination + +```graphql +query paginated_records( + $page: Int = 1 + $per_page: Int = 20 +) { + records( + page: $page + per_page: $per_page + filter: { table: { value: "post" } } + ) { + total_entries + total_pages + has_next_page + has_previous_page + results { id } + } +} +``` + +### Filtering + +```graphql +query filtered_records { + records( + filter: { + table: { value: "product" } + properties: [ + { name: "status", value: "active" } + { name: "price", range: { gte: 10, lte: 100 } } + ] + created_at: { gte: "2024-01-01" } + } + ) { + results { id } + } +} +``` + +--- + +## 10. Users & Authentication + +### User Properties + +Define custom user properties in `app/user.yml`: + +```yaml +properties: + - name: role + type: string + default: customer + - name: first_name + type: string + - name: last_name + type: string + - name: last_sign_in_at + type: datetime +``` + +### Built-in User Fields + +| Field | Description | +|-------|-------------| +| `email` | Unique identifier (case-insensitive) | +| `password` | Virtual field (bcrypt2 hashed) | +| `encrypted_password` | Stored hash | +| `created_at` | Registration timestamp | +| `updated_at` | Last update timestamp | + +### Authentication Flow + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Sign Up │────▶│ Sign In │────▶│ Session │ +│ (Form) │ │ (Form) │ │ (Cookie) │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ + ┌──────┴──────┐ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ Logout │ │ Access │ + │ (Form) │ │ Pages │ + └──────────┘ └──────────┘ +``` + +### Session Management + +```liquid +{# Check if user is logged in #} +{% if context.current_user %} +

Welcome, {{ context.current_user.email }}

+{% else %} + Sign In +{% endif %} + +{# Access user properties #} +{{ context.current_user.properties.role }} +{{ context.current_user.properties.first_name }} +``` + +### Sign In Form + +**File:** `app/forms/sign_in_form.liquid` +```liquid +--- +name: sign_in_form +resource: session +resource_owner: anyone +redirect_to: / +flash_alert: Invalid email or password +--- + +{% form %} + + + +{% endform %} +``` + +### Sign Up Form + +**File:** `app/forms/sign_up_form.liquid` +```liquid +--- +name: sign_up_form +resource: user +resource_owner: anyone +redirect_to: /welcome +flash_notice: Account created! +fields: + email: + validation: + presence: true + email: true + uniqueness: true + password: + validation: + presence: true + length: + minimum: 8 +--- + +{% form %} + + + +{% endform %} +``` + +--- + +## 11. Authorization Policies + +### Creating Policies + +**File:** `app/authorization_policies/valid_user.liquid` +```liquid +--- +name: valid_user_policy +redirect_to: /sign-in +flash_alert: Please sign in to access this page +--- + +{% if context.current_user %} + true +{% else %} + false +{% endif %} +``` + +### Policy Configuration + +| Option | Description | +|--------|-------------| +| `name` | Policy identifier | +| `redirect_to` | Where to redirect if policy fails | +| `flash_alert` | Error message on failure | + +### Associating with Pages + +```liquid +--- +slug: admin/dashboard +authorization_policies: + - valid_user_policy + - admin_only_policy +--- +``` + +### Associating with Forms + +```liquid +--- +name: delete_product_form +resource: product +authorization_policies: + - valid_user_policy + - product_owner_policy +--- +``` + +### Common Policy Patterns + +**Admin Only:** +```liquid +{% if context.current_user.properties.role == 'admin' %} + true +{% else %} + false +{% endif %} +``` + +**Resource Owner:** +```liquid +{% graphql product = 'get_product', id: context.params.id %} +{% if product.record.properties.owner_id == context.current_user.id %} + true +{% else %} + false +{% endif %} +``` + +--- + +## 12. Modules + +### Module Structure + +``` +modules/ +└── my_module/ + ├── public/ + │ ├── views/ + │ ├── forms/ + │ ├── graphql/ + │ └── assets/ + └── private/ + ├── views/ + └── forms/ +``` + +### Module Namespacing + +All module files are prefixed with `modules/MODULE_NAME/`: + +```liquid +{# Reference module partial #} +{% render 'modules/my_module/header' %} + +{# Reference module GraphQL #} +{% graphql result = 'modules/my_module/get_data' %} + +{# Reference module form #} +{% render_form 'modules/my_module/contact_form' %} + +{# Reference module asset #} +{{ 'modules/my_module/style.css' | asset_url }} +``` + +### Installing Modules + +```bash +# Install from Partner Portal +pos-cli modules install module_name + +# Install specific version +pos-cli modules install module_name@1.2.3 +``` + +### Overwriting Module Files + +Create a file with the same path in your `app` directory: + +``` +app/ +└── views/ + └── partials/ + └── modules/ + └── my_module/ + └── header.liquid # Overrides module version +``` + +### Creating Modules + +1. Create directory: `modules/MODULE_NAME/` +2. Add `public/` and/or `private/` subdirectories +3. Structure mirrors `app/` directory +4. Deploy with `pos-cli deploy` + +--- + +## 13. Background Jobs + +### When to Use Background Jobs + +| Use Case | Example | +|----------|---------| +| Email sending | Welcome emails, notifications | +| API calls | Webhooks, external integrations | +| Data processing | Imports, exports, reports | +| Scheduled tasks | Daily cleanup, reminders | +| Long operations | Image processing, batch updates | + +### Background Tag Syntax + +```liquid +{% background + job_id = 'unique_job_id', + delay: 5.0, # Delay in minutes + priority: 'high', # low, default, high + max_attempts: 3, # 1-5 retries + source_name: 'my_job' # Human-readable label +%} + {# Your async code here #} + {% graphql result = 'send_email', to: email %} + {% log result %} +{% endbackground %} +``` + +### Priority Levels + +| Priority | Max Execution | Use Case | +|----------|---------------|----------| +| `high` | 1 minute | Critical, time-sensitive | +| `default` | 5 minutes | Standard operations | +| `low` | 60 minutes | Background processing | + +### Variable Passing + +```liquid +{% assign user_id = context.current_user.id %} +{% assign data = '{"key": "value"}' | parse_json %} + +{% background user_id: user_id, data: data %} + {# Variables available: user_id, data, context #} + {% graphql user = 'get_user', id: user_id %} + {% log user %} +{% endbackground %} +``` + +**IMPORTANT:** Only explicitly passed variables are available inside background blocks. + +### Monitoring Jobs + +```graphql +query list_background_jobs { + background_jobs( + per_page: 10 + sort: [{ created_at: { order: DESC } }] + ) { + results { + id + source_name + priority + attempts + max_attempts + created_at + started_at + completed_at + failed_at + error_message + } + } +} +``` + +--- + +## 14. Notifications + +### Email Notifications + +**File:** `app/emails/welcome_user.liquid` +```liquid +--- +name: welcome_user +to: '{{ form.email }}' +from: 'noreply@example.com' +subject: 'Welcome to Our Platform!' +layout: mailer +--- + +

Welcome, {{ form.name }}!

+

Thank you for joining us.

+ +

Get Started

+``` + +**Email Configuration Options:** + +| Option | Description | +|--------|-------------| +| `name` | Notification identifier | +| `to` | Recipient email (Liquid) | +| `from` | Sender email | +| `subject` | Email subject (Liquid) | +| `layout` | Email layout template | +| `bcc` | BCC recipients | +| `cc` | CC recipients | + +### SMS Notifications + +**File:** `app/smses/verification_code.liquid` +```liquid +--- +name: verification_code +to: '{{ form.phone_number }}' +--- + +Your verification code is: {{ form.verification_code }} +``` + +### API Call Notifications + +**File:** `app/api_calls/webhook.liquid` +```liquid +--- +name: webhook_notification +to: 'https://api.example.com/webhook' +format: json +callback: '' +request_type: POST +headers: > + { + "Authorization": "Bearer {{ context.constants.api_key }}", + "Content-Type": "application/json" + } +--- + +{ + "event": "user_signup", + "user_id": "{{ form.id }}", + "email": "{{ form.email }}", + "timestamp": "{{ 'now' | to_time }}" +} +``` + +### Triggering Notifications + +From forms: +```yaml +--- +name: contact_form +email_notifications: + - contact_confirmation + - admin_notification +api_call_notifications: + - crm_webhook +sms_notifications: + - sms_confirmation +--- +``` + +--- + +## 15. Assets & Uploads + +### Assets (Static Files) + +Assets are files in `app/assets/` that are served via CDN. + +**Directory Structure:** +``` +app/assets/ +├── css/ +│ └── app.css +├── js/ +│ └── app.js +├── images/ +│ └── logo.png +└── fonts/ + └── custom.woff2 +``` + +**Using Assets:** +```liquid + + +Logo +``` + +### User Uploads + +Uploads are dynamic files stored per-record. + +**Table Definition:** +```yaml +name: product +properties: + - name: image + type: upload +``` + +**Form:** +```liquid +{% form %} + +{% endform %} +``` + +**Displaying Uploads:** +```liquid +{% graphql product = 'get_product', id: id %} +{{ product.record.properties.image.file_name }} +``` + +**Upload Properties:** + +| Property | Description | +|----------|-------------| +| `url` | Direct file URL | +| `file_name` | Original filename | +| `content_type` | MIME type | +| `size` | File size in bytes | + +### Assets vs Uploads + +| Aspect | Assets | Uploads | +|--------|--------|---------| +| Location | `app/assets/` | Record properties | +| Use Case | Static files (CSS, JS, logos) | Dynamic content | +| Quantity | Thousands expected | Millions supported | +| CDN | Yes | Yes | +| Max Size | 2GB | 2GB | + +### Direct S3 Upload + +platformOS uses **direct S3 upload** - files go straight to AWS S3 without passing through the application server. + +**Advantages:** +- **Speed** - No middleman, faster uploads +- **Cost** - Less bandwidth and server load +- **Security** - No file processing on app server +- **Scalability** - Handle unlimited concurrent uploads +- **Size** - Up to 5GB single file, 5TB multipart + +**Upload Flow:** +``` +1. User selects file +2. Browser requests signed S3 URL from platformOS +3. Browser uploads directly to S3 +4. S3 returns success +5. platformOS saves file reference to record +``` + +### Upload Configuration Options + +**Table Definition with Options:** +```yaml +name: product +properties: + - name: image + type: upload + options: + public: true # Public or private access + max_size: 5242880 # 5MB in bytes + versions: + - name: thumbnail + resize: '200x200>' # Resize to fit 200x200 + - name: medium + resize: '800x600>' + extensions: + - jpg + - png + - gif +``` + +### Upload Versions + +Automatically generate resized versions: + +```yaml +properties: + - name: photo + type: upload + options: + versions: + - name: thumb + resize: '100x100#' # Exact fit, may crop + - name: medium + resize: '300x300>' # Fit within, no upscale + - name: large + resize: '800x800>' +``` + +**Access versions in Liquid:** +```liquid +{{ product.properties.photo.url }} # Original +{{ product.properties.photo.versions.thumb.url }} # Thumbnail +{{ product.properties.photo.versions.medium.url }} # Medium +``` + +### Image Processing Options + +| Option | Description | Example | +|--------|-------------|---------| +| `resize: '100x100'` | Resize to dimensions | Fit within | +| `resize: '100x100>'` | Resize only if larger | Downscale only | +| `resize: '100x100<'` | Resize only if smaller | Upscale only | +| `resize: '100x100#'` | Exact dimensions | May crop | +| `resize: '100x100^'` | Minimum dimensions | May crop | + +--- + +## 16. Best Practices + +### Code Organization + +``` +app/ +├── views/ +│ ├── pages/ # Route handlers +│ ├── layouts/ # Page wrappers +│ └── partials/ +│ ├── components/ # UI components +│ ├── forms/ # Form partials +│ └── helpers/ # Utility partials +├── forms/ # Form configurations +├── graphql/ # Data queries +│ ├── records/ +│ ├── users/ +│ └── system/ +└── schema/ # Table definitions +``` + +### Naming Conventions + +| Component | Convention | Example | +|-----------|------------|---------| +| Tables | snake_case | `blog_post` | +| Properties | snake_case | `published_at` | +| Pages | snake_case | `about_us.liquid` | +| Partials | snake_case | `header.liquid` | +| Forms | snake_case | `contact_form.liquid` | +| GraphQL | snake_case | `get_blog_posts.graphql` | + +### Security Best Practices + +1. **Always use authorization policies** for protected routes +2. **Validate all inputs** using form validations +3. **Escape output** using Liquid's auto-escaping +4. **Use HTTPS** for all production instances +5. **Store secrets** in Partner Portal constants, not code +6. **Sanitize user content** before displaying + +### Performance Best Practices + +1. **Use pagination** for all list queries +2. **Load related records** in single GraphQL query +3. **Use background jobs** for long operations +4. **Cache expensive queries** using static cache +5. **Optimize images** before uploading as assets +6. **Minimize GraphQL response size** with specific field selection + +### Error Handling + +```liquid +{% graphql result = 'create_record', name: name %} + +{% if result.record_create.errors %} +
+ {% for error in result.record_create.errors %} +

{{ error.message }}

+ {% endfor %} +
+{% else %} +

Success! ID: {{ result.record_create.id }}

+{% endif %} +``` + +--- + +## 17. Common Gotchas & Pitfalls + +### 1. Variable Scope in Background Jobs + +**WRONG:** +```liquid +{% assign user_id = context.current_user.id %} +{% background %} + {{ user_id }} {# nil - not passed #} +{% endbackground %} +``` + +**CORRECT:** +```liquid +{% assign user_id = context.current_user.id %} +{% background user_id: user_id %} + {{ user_id }} {# Works! #} +{% endbackground %} +``` + +### 2. N+1 Query Problem + +**WRONG (N+1 queries):** +```liquid +{% graphql companies = 'get_companies' %} +{% for company in companies.records.results %} + {% graphql programmers = 'get_programmers', company_id: company.id %} + {# Each iteration = 1 query! #} +{% endfor %} +``` + +**CORRECT (single query):** +```graphql +query get_companies_with_programmers { + records( + filter: { table: { value: "company" } } + ) { + results { + id + properties + programmers: related_records( + table: "programmer" + foreign_property: "company_id" + ) { + id + properties + } + } + } +} +``` + +### 3. Form Field Name Format + +**WRONG:** +```liquid + {# Won't bind to form #} +``` + +**CORRECT:** +```liquid + +``` + +### 4. Module File References + +**WRONG:** +```liquid +{% render 'modules/my_module/public/header' %} +``` + +**CORRECT:** +```liquid +{% render 'modules/my_module/header' %} +``` + +### 5. Date/Time Formatting + +**WRONG:** +```liquid +{{ '2024-01-01' | strftime: '%Y' }} {# Error - not a time object #} +``` + +**CORRECT:** +```liquid +{{ '2024-01-01' | to_time | strftime: '%Y' }} +``` + +### 6. Array vs JSONB Confusion + +**Arrays** - for simple lists: +```yaml +type: array +# Value: ["a", "b", "c"] +``` + +**JSONB** - for complex objects: +```yaml +type: jsonb +# Value: {"nested": {"key": "value"}} +``` + +### 7. Form Resource Owner + +**For public forms** (contact, newsletter): +```yaml +resource_owner: anyone +``` + +**For authenticated forms** (profile edit): +```yaml +resource_owner: self +``` + +**For admin forms**: +```yaml +resource_owner: anyone_with_token +authorization_policies: + - admin_only_policy +``` + +### 8. Whitespace in Liquid + +**Problem:** Extra whitespace in output +```liquid +{% if true %} + Content +{% endif %} +{# Outputs newlines around content #} +``` + +**Solution:** Use whitespace control +```liquid +{%- if true -%} + Content +{%- endif -%} +``` + +### 9. GraphQL Variable Types + +**Integer vs Float:** +```graphql +# Integer property +{ name: "count", value_int: 5 } + +# Float property +{ name: "price", value_float: 19.99 } +``` + +**Boolean:** +```graphql +{ name: "active", value_boolean: true } +``` + +### 10. Soft Delete vs Hard Delete + +**Soft delete** (default): +```graphql +mutation { + record_delete(id: "123") { + id + deleted_at # Timestamp set + } +} +``` + +**Hard delete** (permanent): +```graphql +mutation { + record_delete(id: "123", hard_delete: true) { + id + } +} +``` + +### 11. Reserved Names + +Avoid these reserved names for custom tables and properties: + +**System Fields (automatically created):** +- `id` - Record UUID +- `created_at` - Creation timestamp +- `updated_at` - Last update timestamp +- `deleted_at` - Soft delete timestamp +- `type_name` - Table name +- `properties` - Property container + +**Reserved Words:** +- `user`, `users` - Built-in User table +- `session`, `sessions` - Session management +- `record`, `records` - Record operations +- `constant`, `constants` - System constants +- `table`, `tables` - Table metadata + +### 12. Form Resource Owner Confusion + +| Value | When to Use | +|-------|-------------| +| `anyone` | Public forms (contact, newsletter) | +| `self` | User editing their own data | +| `anyone_with_token` | API endpoints with token auth | + +**Wrong:** +```yaml +resource_owner: self # Won't work for public contact form +``` + +**Correct:** +```yaml +resource_owner: anyone # For public forms +``` + +### 13. Module File Deletion Behavior + +By default, module files are **NOT deleted** during deploy to protect private files. + +To enable deletion for a module: +```yaml +# app/config.yml +modules_that_allow_delete_on_deploy: + - my_module +``` + +### 14. GraphQL Query Caching + +GraphQL queries are cached by default. To bypass cache: +```graphql +query { + records( + per_page: 10 + filter: { table: { value: "product" } } + ) @skip_cache { + results { id } + } +} +``` + +### 15. File Upload Size Limits + +| Upload Type | Max Size | +|-------------|----------| +| Direct S3 (single part) | 5 GB | +| Direct S3 (multipart) | 5 TB | +| Application-processed | 2 GB | + +### 16. Background Job Payload Limits + +```liquid +{# WRONG - payload too large #} +{% background data: huge_array_with_thousands_of_items %} + +{# CORRECT - pass reference only #} +{% background record_id: record_id %} + {% graphql record = 'get_record', id: record_id %} + {# Process data in background #} +{% endbackground %} +``` + +### 17. Liquid Truthiness + +In Liquid, only `nil` and `false` are falsy. Empty strings and zero are truthy: + +```liquid +{% if '' %}TRUE{% endif %} {# TRUE! #} +{% if 0 %}TRUE{% endif %} {# TRUE! #} +{% if empty_array %}TRUE{% endif %} {# FALSE (nil) #} +{% if false %}TRUE{% endif %} {# FALSE #} +``` + +Use `blank` and `present` for better checks: +```liquid +{% if '' == blank %}EMPTY{% endif %} {# EMPTY #} +{% if 0 == blank %}ZERO IS BLANK{% endif %} {# Not blank! #} +``` + +--- + +## 18. Performance Optimization + +### Measuring Performance + +**time_diff filter:** +```liquid +{% assign start = 'now' | to_time %} + +{% graphql posts = 'get_posts' %} + +{% assign duration = start | time_diff: 'now' %} +

Query took: {{ duration }}ms

+``` + +### Query Optimization + +**1. Select only needed fields:** +```graphql +# BAD - fetches everything +query { + records { results { properties } } +} + +# GOOD - specific fields +query { + records { + results { + id + properties + } + } +} +``` + +**2. Use pagination:** +```graphql +query { + records(per_page: 20, page: 1) { + total_entries + results { id } + } +} +``` + +**3. Load related records efficiently:** +```graphql +query { + records(filter: { table: { value: "order" } }) { + results { + id + items: related_records(table: "order_item") { + id + properties + } + } + } +} +``` + +### Caching Strategies + +**Static Cache (Edge Caching):** +```liquid +--- +slug: public-page +response_headers: + Cache-Control: public, max-age=3600 +--- +``` + +**Fragment Caching:** +```liquid +{% cache key: 'sidebar', expire: 3600 %} + {% graphql categories = 'get_categories' %} + {% for category in categories.records.results %} + {{ category.properties.name }} + {% endfor %} +{% endcache %} +``` + +### Background Job Optimization + +**Keep payloads small:** +```liquid +{# BAD - large payload #} +{% background data: huge_array %} + +{# GOOD - pass reference #} +{% assign job_id = 'process_' | append: record_id %} +{% background job_id: job_id, record_id: record_id %} + {% graphql record = 'get_record', id: record_id %} + {# Process in background #} +{% endbackground %} +``` + +--- + +## 19. Testing & CI/CD + +### pos-cli GUI + +```bash +# Start GUI for GraphQL development +pos-cli gui serve staging + +# Access at http://localhost:3333 +``` + +### platformOS Check + +```bash +# Install +npm install -g @platformos/platformos-check + +# Run checks +platformos-check + +# Auto-fix issues +platformos-check --auto-correct +``` + +### GitHub Actions CI + +**File:** `.github/workflows/platformos.yml` +```yaml +name: platformOS CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install pos-cli + run: npm install -g @platformos/pos-cli + + - name: Deploy to Staging + run: pos-cli deploy staging + env: + MPKIT_TOKEN: ${{ secrets.MPKIT_TOKEN }} + MPKIT_URL: ${{ secrets.STAGING_URL }} + + - name: Run Tests + run: npm test +``` + +### Release Pool Setup + +1. Create dedicated test instances in Partner Portal +2. Configure GitHub secrets: + - `MPKIT_TOKEN` + - `STAGING_URL` + - `PRODUCTION_URL` + +### Testing Best Practices + +1. **Unit test** GraphQL queries +2. **Integration test** form submissions +3. **E2E test** critical user flows +4. **Performance test** with realistic data volumes +5. **Security test** authorization policies + +--- + +## 20. System Limitations + +### Resource Limits + +| Resource | Limit | Notes | +|----------|-------|-------| +| File upload size | 2GB | Assets and uploads | +| Background job payload | 100KB | Keep payloads small | +| Background job execution | 1-60 min | Depends on priority | +| GraphQL query complexity | Varies | Monitor performance | +| Records per query | Unlimited | Use pagination | +| Assets | Thousands | Use uploads for dynamic content | +| Uploads | Millions | No practical limit | + +### Background Job Limits + +| Priority | Max Execution | Use For | +|----------|---------------|---------| +| `high` | 1 minute | Critical, urgent tasks | +| `default` | 5 minutes | Standard operations | +| `low` | 60 minutes | Heavy processing | + +### Rate Limiting + +- API calls may be rate-limited based on plan +- Background job scheduling has queue limits +- GraphQL queries have complexity scoring + +### Reserved Names + +Avoid these names for custom tables/properties: +- `id`, `created_at`, `updated_at`, `deleted_at` +- `type_name`, `properties`, `user` +- Built-in Liquid objects and filters + +--- + +## 22. Data Import/Export + +### Exporting Data + +```bash +# Export all data from an instance +pos-cli data export staging --path=./export.json + +# Export specific tables +pos-cli data export staging --tables=products,orders --path=./products.json +``` + +### Importing Data + +```bash +# Import data to an instance +pos-cli data import staging ./export.json + +# Import with transformations +pos-cli data import staging ./data.json --transform=./transform.js +``` + +### Data Export Format + +```json +{ + "users": [ + { + "id": "123", + "email": "user@example.com", + "created_at": "2024-01-15T10:00:00Z", + "properties": { + "first_name": "John", + "last_name": "Doe" + } + } + ], + "records": { + "product": [ + { + "id": "456", + "properties": { + "name": "Widget", + "price": 19.99 + } + } + ] + } +} +``` + +### Programmatic Import with Migrations + +```liquid +{# app/migrations/20240115000000_import_products.liquid #} +{% parse_json data %} + {{ 'data/products.json' | load_file }} +{% endparse_json %} + +{% for product in data.products %} + {% graphql result = 'create_product', + name: product.name, + price: product.price, + sku: product.sku + %} + {% log result %} +{% endfor %} +``` + +### Cleaning Instance Data + +```bash +# WARNING: This deletes all data! +pos-cli data clean staging + +# Clean specific tables +pos-cli data clean staging --tables=products,orders +``` + +--- + +## 23. Quick Reference + +### File Templates + +**New Page:** +```liquid +--- +slug: my-page +layout: application +--- + +

Page Title

+``` + +**New Table:** +```yaml +name: my_table +properties: + - name: name + type: string +``` + +**New Form:** +```liquid +--- +name: my_form +resource: my_table +resource_owner: anyone +redirect_to: /success +fields: + properties: + name: + validation: + presence: true +--- + +{% form %} + + +{% endform %} +``` + +**New GraphQL Query:** +```graphql +query my_query($param: String) { + records(filter: { table: { value: "my_table" } }) { + results { id properties } + } +} +``` + +### Common Liquid Patterns + +**Conditional rendering:** +```liquid +{% if condition %} + +{% elsif other_condition %} + +{% else %} + +{% endif %} +``` + +**Loop with index:** +```liquid +{% for item in items %} + {{ forloop.index }}: {{ item.name }} +{% endfor %} +``` + +**Pagination:** +```liquid +{% if records.has_previous_page %} + Previous +{% endif %} + +{% if records.has_next_page %} + Next +{% endif %} +``` + +### Common GraphQL Patterns + +**Create with error handling:** +```graphql +mutation { + record_create(record: { table: "post", properties: [] }) { + id + errors { message } + } +} +``` + +**Update specific fields:** +```graphql +mutation { + record_update(id: "123", record: { properties: [{ name: "status", value: "published" }] }) { + id + properties + } +} +``` + +**Search with filters:** +```graphql +query { + records( + filter: { + table: { value: "product" } + properties: [{ name: "category", value: "electronics" }] + created_at: { gte: "2024-01-01" } + } + ) { + results { id } + } +} +``` + +### pos-cli Commands + +```bash +# Authentication +pos-cli auth login # Login to Partner Portal + +# Development +pos-cli sync staging # Watch and sync changes +pos-cli deploy staging # Deploy to instance +pos-cli deploy staging -f # Force deploy (delete missing files) + +# Data +pos-cli data export staging # Export instance data +pos-cli data import staging file.json # Import data +pos-cli migrations run staging # Run pending migrations + +# Modules +pos-cli modules install module_name # Install module +pos-cli modules remove module_name # Remove module + +# GUI +pos-cli gui serve staging # Start development GUI + +# Logs +pos-cli logs staging # Stream logs +``` + +### Error Messages Reference + +| Error | Cause | Solution | +|-------|-------|----------| +| `Record not found` | Invalid ID | Check record exists | +| `Validation failed` | Invalid data | Check form validations | +| `Unauthorized` | Policy failed | Check authorization | +| `Rate limited` | Too many requests | Add delays, use caching | +| `Timeout` | Query too slow | Optimize query, add pagination | +| `Property not found` | Wrong property name | Check table schema | +| `Table not found` | Wrong table name | Check table definition | +| `Form not found` | Wrong form name | Check form file exists | + +### GraphQL Property Type Mapping + +| Property Type | GraphQL Input | Example | +|---------------|---------------|---------| +| `string` | `value: "text"` | `{ name: "title", value: "Hello" }` | +| `integer` | `value_int: 42` | `{ name: "count", value_int: 5 }` | +| `float` | `value_float: 19.99` | `{ name: "price", value_float: 19.99 }` | +| `boolean` | `value_boolean: true` | `{ name: "active", value_boolean: true }` | +| `date` | `value: "2024-01-15"` | `{ name: "birthday", value: "2024-01-15" }` | +| `datetime` | `value: "2024-01-15T10:00:00Z"` | ISO 8601 format | +| `array` | `value_array: ["a", "b"]` | `{ name: "tags", value_array: ["a", "b"] }` | +| `jsonb` | `value_json: "{}"` | JSON string | +| `upload` | Via form only | File uploads | + +### Form Validation Reference + +| Validation | Syntax | Description | +|------------|--------|-------------| +| `presence` | `presence: true` | Required field | +| `email` | `email: true` | Valid email format | +| `uniqueness` | `uniqueness: true` | Must be unique | +| `length` | `length: { minimum: 5, maximum: 100 }` | String length | +| `numericality` | `numericality: { greater_than: 0 }` | Number range | +| `confirmation` | `confirmation: true` | Must match confirmation field | +| `url` | `url: true` | Valid URL format | + +### pos-cli Extended Commands + +```bash +# Authentication +pos-cli auth login # Login to Partner Portal +pos-cli auth logout # Logout + +# Development +pos-cli sync staging # Watch and sync changes +pos-cli sync staging --live-reload # With live reload +pos-cli deploy staging # Deploy to instance +pos-cli deploy staging -f # Force deploy (delete missing files) +pos-cli deploy staging --direct-assets # Deploy assets directly + +# Data Management +pos-cli data export staging # Export all data +pos-cli data export staging --tables=products,orders +pos-cli data import staging file.json # Import data +pos-cli data clean staging # Delete all data (DANGER!) +pos-cli migrations run staging # Run pending migrations +pos-cli migrations status staging # Check migration status + +# Modules +pos-cli modules install module_name # Install module +pos-cli modules install module_name@1.2 # Specific version +pos-cli modules remove module_name # Remove module +pos-cli modules list staging # List installed modules + +# GUI Tools +pos-cli gui serve staging # Start development GUI +pos-cli gui serve staging --port 3333 # Custom port + +# Logs +pos-cli logs staging # Stream logs +pos-cli logs staging --tail 100 # Last 100 lines +pos-cli logs staging --follow # Follow new logs + +# Environment +pos-cli env list # List environments +pos-cli env add production # Add environment +pos-cli env remove staging # Remove environment + +# Testing +pos-cli test staging # Run tests + +# Debug +pos-cli shell staging # Interactive shell +``` + +--- + +## 24. Translations + +### Overview + +Translations serve three main purposes: +1. **Multi-language sites** - Static copy in multiple languages +2. **Date formatting** - Consistent date/time display +3. **Flash messages** - System message localization + +### Translation Files + +**File:** `app/translations/en.yml` +```yaml +en: + hello: "Hello" + welcome: "Welcome to our site" + buttons: + submit: "Submit" + cancel: "Cancel" + errors: + not_found: "Page not found" +``` + +**File:** `app/translations/es.yml` +```yaml +es: + hello: "Hola" + welcome: "Bienvenido a nuestro sitio" + buttons: + submit: "Enviar" + cancel: "Cancelar" + errors: + not_found: "Página no encontrada" +``` + +### Using Translations in Liquid + +**Basic translation:** +```liquid +{{ 'hello' | t }} # Output: Hello (or Hola) +``` + +**Nested keys:** +```liquid +{{ 'buttons.submit' | t }} # Output: Submit +{{ 'errors.not_found' | t }} # Output: Page not found +``` + +**With interpolation:** +```yaml +# en.yml +welcome_user: "Welcome, {{ name }}!" +``` +```liquid +{{ 'welcome_user' | t: name: user.first_name }} +``` + +### Date Localization + +Use the `l` (localize) filter for consistent date formatting: + +```yaml +# en.yml +date: + formats: + short: "%b %d, %Y" + long: "%B %d, %Y %H:%M" +``` +```liquid +{{ 'now' | l: 'short' }} # Jan 15, 2024 +{{ post.published_at | l: 'long' }} # January 15, 2024 14:30 +``` + +### Language Detection + +platformOS automatically detects language from: +1. User's `language` property (if set) +2. Browser's Accept-Language header +3. Default language (English) + +Access current language: +```liquid +{{ context.language }} # Current language code (e.g., "en") +``` + +--- + +## 25. Activity Feeds + +### Overview + +Activity Feeds implement the [W3C Activity Streams 2.0](https://www.w3.org/TR/2017/REC-activitystreams-core-20170523/) specification for tracking user activities. + +**Key Characteristics:** +- Activities are **immutable** (append-only) +- Each activity has a **unique UUID** +- Activities can be shared between actors +- Activities represent events that happened in the past + +### Activity Structure + +```json +{ + "actor": { + "type": "Person", + "id": "User.1", + "name": "Sally Smith" + }, + "type": "Create", + "object": { + "type": "Relationship", + "id": "Relationship.42" + }, + "target": { + "type": "Group", + "id": "Group.5" + } +} +``` + +### Creating Activities + +**GraphQL Mutation:** +```graphql +mutation create_activity { + activity_create( + activity: { + type: "Join" + actor: { + type: "Person" + id: "User.123" + name: "John Doe" + } + object: { + type: "Group" + id: "Group.456" + } + } + ) { + id + uuid + } +} +``` + +### Publishing to Feeds + +After creating an activity, publish it to feeds: + +```graphql +mutation publish_to_feed { + feed_publish( + feed_id: "user_123_notifications" + activity_uuid: "abc-123-uuid" + ) { + id + } +} +``` + +### Querying Feeds + +```graphql +query get_user_feed { + feeds( + feed_id: "user_123_notifications" + per_page: 20 + ) { + total_entries + results { + id + uuid + type + actor + object + target + created_at + } + } +} +``` + +### Common Activity Types + +| Type | Description | +|------|-------------| +| `Create` | Created something | +| `Update` | Updated something | +| `Delete` | Deleted something | +| `Join` | Joined a group/event | +| `Leave` | Left a group/event | +| `Follow` | Started following | +| `Like` | Liked content | +| `Comment` | Commented on content | +| `Share` | Shared content | +| `Approve` | Approved a request | + +--- + +## 26. JSON Documents + +### Overview + +JSON Documents provide a schemaless data storage option for flexible, document-based data. Unlike Records (which require a Table schema), JSON Documents can store any valid JSON structure. + +**Use Cases:** +- Configuration data +- Unstructured content +- Temporary data storage +- Data that doesn't fit a rigid schema + +### Creating JSON Documents + +**GraphQL Mutation:** +```graphql +mutation create_json_document { + json_document_create( + document: { + name: "site_config" + content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}" + } + ) { + id + name + content + created_at + } +} +``` + +### Querying JSON Documents + +```graphql +query get_json_document { + json_document(name: "site_config") { + id + name + content + created_at + updated_at + } +} + +query list_json_documents { + json_documents( + per_page: 10 + sort: [{ created_at: { order: DESC } }] + ) { + results { + id + name + content + } + } +} +``` + +### Updating JSON Documents + +```graphql +mutation update_json_document { + json_document_update( + name: "site_config" + document: { + content: "{\"theme\": \"light\", \"features\": [\"blog\", \"shop\", \"forum\"]}" + } + ) { + id + content + updated_at + } +} +``` + +### Using in Liquid + +```liquid +{% graphql config = 'get_json_document', name: 'site_config' %} +{% assign settings = config.json_document.content | parse_json %} + +Theme: {{ settings.theme }} +Features: {{ settings.features | join: ', ' }} +``` + +### JSON Document vs Records + +| Feature | JSON Documents | Records | +|---------|---------------|---------| +| Schema | Schemaless | Defined in Table YAML | +| Validation | None | Form validation | +| Structure | Any JSON | Fixed properties | +| Use Case | Config, flexible data | Structured entities | +| GraphQL | `json_document_*` | `record_*` | + +--- + +## 27. AI Embeddings + +### Overview + +platformOS supports AI embeddings for semantic search and similarity matching. Embeddings are vector representations of text that capture semantic meaning. + +**Use Cases:** +- Semantic search +- Content recommendation +- Similarity matching +- Clustering + +### Creating Embeddings + +**GraphQL Mutation:** +```graphql +mutation create_embedding { + embedding_create( + embedding: { + name: "product_description" + value: "High-quality wireless headphones with noise cancellation" + target_id: "product_123" + target_type: "Product" + } + ) { + id + vector + } +} +``` + +### Semantic Search + +```graphql +query semantic_search { + embeddings_search( + query: "wireless audio devices" + limit: 10 + threshold: 0.7 + ) { + results { + id + target_id + target_type + similarity + value + } + } +} +``` + +### Querying Embeddings + +```graphql +query get_embedding { + embedding( + target_id: "product_123" + target_type: "Product" + ) { + id + name + value + vector + created_at + } +} +``` + +### Deleting Embeddings + +```graphql +mutation delete_embedding { + embedding_delete( + target_id: "product_123" + target_type: "Product" + ) { + id + } +} +``` + +### Embedding Parameters + +| Parameter | Description | +|-----------|-------------| +| `name` | Identifier for the embedding type | +| `value` | The text to embed | +| `target_id` | ID of the associated entity | +| `target_type` | Type of the associated entity | +| `vector` | The computed embedding vector (read-only) | + +--- + +## 28. Migrations + +### Overview + +Migrations are Liquid scripts that run once to transform data. They are useful for: +- Data transformations during schema changes +- Bulk data updates +- One-time data imports + +### Creating Migrations + +**File:** `app/migrations/20240115120000_add_status_to_products.liquid` +```liquid +{% graphql products = 'get_all_products' %} + +{% for product in products.records.results %} + {% graphql result = 'update_product_status', + id: product.id, + status: 'active' + %} + {% log result %} +{% endfor %} +``` + +### Migration File Naming + +Migrations are executed in alphabetical order. Use timestamps as prefixes: +``` +app/migrations/ +├── 20240101000000_initial_setup.liquid +├── 20240115120000_add_status.liquid +└── 20240201000000_migrate_images.liquid +``` + +### Running Migrations + +```bash +# Run pending migrations +pos-cli migrations run staging + +# Check migration status +pos-cli migrations status staging +``` + +### Migration Best Practices + +1. **Make migrations idempotent** - Running twice should not cause errors: +```liquid +{% graphql product = 'get_product', id: product_id %} +{% unless product.record.properties.status %} + {# Only update if status is not set #} + {% graphql result = 'update_product', id: product_id, status: 'active' %} +{% endunless %} +``` + +2. **Use background jobs for large migrations:** +```liquid +{% background source_name: 'data_migration' %} + {% graphql records = 'get_all_records' %} + {% for record in records.records.results %} + {# Process each record #} + {% endfor %} +{% endbackground %} +``` + +3. **Test migrations on staging first** +4. **Log progress for debugging:** +```liquid +{% log 'Migration started' %} +{% log 'Processed ' | append: count | append: ' records' %} +``` + +### Migration Limitations + +- Migrations run as background jobs +- Should complete within a few minutes +- For long-running operations, use low-priority background jobs +- Failed migrations can be retried + +--- + +## Resources + +- **Documentation:** https://documentation.platformos.com/ +- **API Reference:** https://documentation.platformos.com/api-reference +- **Examples:** https://examples.platform-os.com/ +- **GitHub:** https://github.com/Platform-OS +- **Partner Portal:** https://partners.platformos.com/ +- **Community:** https://community.platformos.com/ + +--- + +*This guide is designed for LLM agents developing on platformOS. For the most up-to-date information, always refer to the official documentation.* diff --git a/src/data/resources/platformos-development-guide.md b/src/data/resources/platformos-development-guide.md index 4cbe916..d63294e 100644 --- a/src/data/resources/platformos-development-guide.md +++ b/src/data/resources/platformos-development-guide.md @@ -1,1544 +1,1172 @@ -# platformOS Development Guide for LLM Agents - -> **Essential Knowledge Base for AI Coding Agents** -> Version: 2025-2026 | Last Updated: April 2026 -> Source: [platformOS Documentation](https://documentation.platformos.com/) - ---- - -## Table of Contents - -1. [Introduction & Architecture](#1-introduction--architecture) -2. [Directory Structure](#2-directory-structure) -3. [Core Concepts](#3-core-concepts) -4. [Pages & Layouts](#4-pages--layouts) -5. [Records & Tables](#5-records--tables) -6. [Properties](#6-properties) -7. [Forms](#7-forms) -8. [Liquid Templating](#8-liquid-templating) -9. [GraphQL API](#9-graphql-api) -10. [Users & Authentication](#10-users--authentication) -11. [Authorization Policies](#11-authorization-policies) -12. [Modules](#12-modules) -13. [Background Jobs](#13-background-jobs) -14. [Notifications](#14-notifications) -15. [Assets & Uploads](#15-assets--uploads) -16. [Best Practices](#16-best-practices) -17. [Common Gotchas & Pitfalls](#17-common-gotchas--pitfalls) -18. [Performance Optimization](#18-performance-optimization) -19. [Testing & CI/CD](#19-testing--cicd) -20. [System Limitations](#20-system-limitations) -21. [Data Import/Export](#22-data-importexport) -22. [Quick Reference](#23-quick-reference) -23. [Translations](#24-translations) -24. [Activity Feeds](#25-activity-feeds) -25. [JSON Documents](#26-json-documents) -26. [AI Embeddings](#27-ai-embeddings) -27. [Migrations](#28-migrations) +# platformOS Development Guide + +Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory +workflow — read it before touching any file. + +## 0. MANDATORY WORKFLOW — Read Before Writing Any Code + +**You are STRICTLY FORBIDDEN from skipping this workflow** + +You MUST follow this loop for every feature. Each step produces structured output +the next step consumes — skipping any step produces invalid state that downstream +tools will reject. + +1. **`project_map`** — understand what already exists. MUST be called once per session + before any scaffold or write. +2. **`scaffold(type, name, properties, write: false)`** — generate the authoritative + file set from platformOS-native templates. MUST use scaffold whenever a file set + matches one of its types (crud, api, command, query, partial, page). +3. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files. + Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains + rules that are NOT in your training data and that differ from Shopify, Rails, and + generic Liquid. +4. **`validate_intent` — declare your plan before touching disk.** + Two modes, pick by what you're doing next: + + - **Mode A — hand-drafted batch (REQUIRED before manual writes).** + Call `validate_intent({ intent: { goal, changes: [...] } })` where + `changes` is an array of `{ path, role, action, references? }` — one + entry per file you intend to author. The plan is the contract for the + rest of the session. + - **Mode B — scaffold review (OPTIONAL).** + Call `validate_intent({ scaffold_output: })` + only if you want a second look at the generated set before committing. + The default scaffold path skips this step. + + **Read the response:** + - `ok: false` → fix `errors[].suggestion`, re-call. MUST NOT proceed. + - `ok: true` + `write_directly: true` → Mode B; go straight to + `scaffold(..., write: true)`. + - `ok: true` + `write_directly: false` → Mode A; draft each file, call + `validate_code` on the full content, then write. + + **What `pending_files` / `pending_translations` / `pending_pages` are for:** + you can ignore them. The supervisor stores them and uses them to suppress + false-positive `MissingPartial` / `TranslationKeyExists` errors in later + `validate_code` / `analyze_project` calls — because those files are + *promised* by the plan but not on disk yet. You do not pass them to any + subsequent tool; the server merges them automatically. + + **Skipping Mode A before hand-drafted writes** is the #1 cause of phantom + cross-reference errors: `validate_code` will flag every partial and + translation key the plan hasn't written yet, and the agent chases those + ghosts by deleting the references the plan needs. + + **Scope drift:** if you add, rename, or drop a file that isn't in the + current `changes` array, re-call `validate_intent` with the updated plan + before writing the new file. + +5. **`scaffold(..., write: true)`** — writes all files to disk. If you went + through Mode B in step 4, this runs after `write_directly: true`. + Otherwise this is the direct follow-up to step 2. For hand-drafted edits + (Mode A, or manual edits without scaffold), call `validate_code` per file + and only write when validation passes — never rely on scaffold to write a + hand-authored file. +6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or + `must_fix_before_write: true`, fix every error and re-validate. MUST NOT + write the file to disk until validation passes. +7. Creation order matters: schema → graphql → partial → page. +8. **`analyze_project` — project-wide health check.** MUST be called: + - **Before reporting task completion.** `validate_code` only sees one + file at a time; cross-file damage (broken render targets, orphaned + partials, dangling translations, schema drift) only surfaces from the + whole-project view. A task is not done until `analyze_project` returns + zero new errors or warnings introduced by this session. + - **When you feel lost.** If validate_code keeps reporting errors you + don't understand, if the same check keeps re-appearing after you + "fixed" it, if you suspect a file you edited affected callers you + can't see, or if `project_map` no longer matches your mental model — + stop editing and call `analyze_project` to re-ground. It returns + per-file error counts, the dependency graph, orphaned files, broken + references, and schema issues for every file in `app/`. That is the + authoritative picture of the project right now. + + `analyze_project` respects `session.pending` — files declared in a + validated plan are not flagged as missing. You do not need to pass any + parameters for the standard case; omit `files` to analyze the whole + project. + + MUST NOT: skip this step before announcing "done" just because + `validate_code` passed on the files you edited. Individual-file green + lights do not imply project integrity. + +### MUST-CALL domains (by feature type) + +- **Auth code** — `domain_guide(domain: "authentication")` +- **Any form** — `domain_guide(domain: "forms")` +- **New pages** — `domain_guide(domain: "pages")` +- **New partials** — `domain_guide(domain: "partials")` +- **GraphQL ops** — `domain_guide(domain: "graphql")` +- **Any new domain** — `domain_guide(domain: "", section: "gotchas")` + +### MUST NOT + +- Use `{% include %}` for app code — deprecated. Use `{% render %}` or + `{% function %}`. +- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These + do not exist in platformOS. +- Write files to disk without calling `validate_code` on the proposed content first. +- Assume module call syntax from memory — call `module_info(name)` to get the + authoritative live-scan API surface. +- Ignore `consult_before_writing` in a scaffold response. Every domain listed there + MUST be consulted via `domain_guide` before step 5. + +### Session-start checklist + +Before your first tool call, the following are true: + +- [ ] `server_status` called — confirms LSP and indexes are ready, lists + `domain_guides` and `session_pending`. +- [ ] `load_development_guide` called (this document) — re-read if you lose + context or are unsure which step comes next. +- [ ] `project_map` called once for full project baseline. + +Proceed only when all three are checked. --- -## 1. Introduction & Architecture +## 1. Technology Stack -### What is platformOS? +platformOS uses three primary technologies: +- **Liquid** — server-side templating language +- **GraphQL** — data operations (built-in queries/mutations only) +- **YAML** — configuration for schemas, translations, and settings -platformOS is a **model-based application development platform** (PaaS) that enables developers to build web applications, APIs, and digital products without managing infrastructure. It combines: +The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access. -- **Liquid templating** for views -- **GraphQL** for data queries and mutations -- **YAML configuration** for schema definition -- **Background job processing** for async operations -- **Built-in authentication & authorization** +platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag. -### Key Architectural Principles +### Source of Truth -| Principle | Description | -|-----------|-------------| -| **Convention over Configuration** | File locations determine behavior | -| **Git-based Workflow** | Version control everything | -| **Multi-tenancy** | Multiple instances per codebase | -| **Serverless Backend** | No server management required | -| **Edge Caching** | Built-in CDN for performance | +The official platformOS documentation is the ONLY source of truth: -### Development Workflow +| Resource | URL | +|----------|-----| +| Official Docs | documentation.platformos.com | +| GraphQL Schema | documentation.platformos.com/api/graphql/schema | +| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md | +| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md | +| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md | +| Core Module | github.com/Platform-OS/pos-module-core (README) | +| User Module | github.com/Platform-OS/pos-module-user (README) | +| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) | +| Payments Module | github.com/Platform-OS/pos-module-payments (README) | +| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) | +| Tests Module | github.com/Platform-OS/pos-module-tests (README) | +| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md | -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Local │───▶│ Test │───▶│ Staging │───▶│ Production │ -│ Development │ │ Instance │ │ Instance │ │ Instance │ -└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ - │ │ │ │ - └──────────────────┴──────────────────┴──────────────────┘ - pos-cli deploy -``` +You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation. --- ## 2. Directory Structure -### Required Directory Layout - ``` project-root/ -├── app/ # Main application code -│ ├── assets/ # Static files (CSS, JS, images) -│ ├── authorization_policies/ # Access control rules -│ ├── emails/ # Email notification templates -│ ├── api_calls/ # API call notifications -│ ├── smses/ # SMS notification templates -│ ├── forms/ # Form configurations -│ ├── graphql/ # GraphQL query files -│ ├── migrations/ # Data migration scripts -│ ├── schema/ # Table definitions (YAML) +├── app/ +│ ├── assets/ # Static files (images, fonts, styles, scripts) │ ├── views/ -│ │ ├── layouts/ # Page layouts -│ │ ├── pages/ # Page definitions -│ │ └── partials/ # Reusable Liquid snippets -│ ├── config.yml # App configuration -│ └── user.yml # User property definitions -├── modules/ # External modules +│ │ ├── pages/ # Controllers — NO HTML here +│ │ ├── layouts/ # Wrapper templates +│ │ └── partials/ # Reusable template snippets +│ ├── lib/ +│ │ ├── commands/ # Business logic (build -> check -> execute) +│ │ ├── queries/ # Data retrieval wrappers +│ │ ├── events/ # Event definitions +│ │ └── consumers/ # Event handlers +│ ├── schema/ # Database table definitions (YAML) +│ ├── graphql/ # GraphQL query/mutation files +│ ├── forms/ # Form configurations (YAML + Liquid front matter) +│ ├── emails/ # Email templates +│ ├── smses/ # SMS templates +│ ├── api_calls/ # Third-party API integrations +│ ├── translations/ # i18n content (YAML) +│ ├── authorization_policies/ # Access control rules (page/form level) +│ ├── migrations/ # One-time migration scripts +│ └── config.yml # Feature flags +├── modules/ # Downloaded/custom modules (READ-ONLY) │ └── MODULE_NAME/ -│ ├── public/ # Publicly accessible files -│ └── private/ # IP-protected files -└── .pos # pos-cli configuration +│ ├── public/ # Publicly accessible files +│ └── private/ # IP-protected files (not downloadable) +└── .pos # Environment endpoints ``` -### Critical File Locations +All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`. -| Component | Required Path | Extension | -|-----------|---------------|-----------| -| Pages | `app/views/pages/` | `.liquid` | -| Layouts | `app/views/layouts/` | `.liquid` | -| Partials | `app/views/partials/` | `.liquid` | -| Tables | `app/schema/` | `.yml` | -| Forms | `app/forms/` | `.liquid` | -| GraphQL | `app/graphql/` | `.graphql` | -| Assets | `app/assets/` | any | +The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only. -### Configuration Files +### Module Structure Details -**`.pos` (pos-cli config):** -```yaml -staging: - url: https://staging.example.com - email: dev@example.com -production: - url: https://www.example.com - email: dev@example.com +Modules have `public/` and `private/` subdirectories with the same internal structure: + +``` +modules/my_module/ +├── public/ +│ ├── views/ +│ ├── forms/ +│ ├── graphql/ +│ └── assets/ +└── private/ + ├── views/ + └── forms/ +``` + +- **Public files** — accessible for preview/download after deployment +- **Private files** — IP-protected, not accessible for download +- When referencing module files, omit `public/` and `private/` from the path +- Files with the same name in both directories will conflict — do not do this + +**Module file referencing:** +```liquid +{% render 'modules/my_module/header' %} +{% graphql result = 'modules/my_module/get_data' %} +{% render_form 'modules/my_module/contact_form' %} +{{ 'modules/my_module/style.css' | asset_url }} ``` -**`app/config.yml`:** +**Module deletion behavior:** By default, module files are NOT deleted during `pos-cli deploy` to protect private files. To enable deletion: ```yaml -# Modules that can be deleted during deploy +# app/config.yml modules_that_allow_delete_on_deploy: - my_module - -# Other app-level configuration ``` +### File Naming Conventions + +| Directory | Pattern | Example | +|-----------|---------|---------| +| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` | +| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` | +| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` | +| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` | +| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` | +| Assets | `app/assets//` | `app/assets/images/logo.png` | +| Translations | `app/translations/.yml` | `app/translations/en.yml` | + +### File Formats + +| Extension | Content-Type | URL | +|-----------|--------------|-----| +| `*.liquid` or `*.html.liquid` | `text/html` | `/path` | +| `*.json.liquid` | `application/json` | `/path.json` | +| `*.js.liquid` | `application/javascript` | `/path.js` | + --- -## 3. Core Concepts +## 3. Architecture Rules -### The platformOS Data Flow +### Pages MUST Be Controllers -``` -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ Client │───▶│ Router │───▶│ Liquid │───▶│ GraphQL │ -│ Request │ │ (Page) │ │ Template │ │ Query │ -└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ - │ - ┌────▼─────┐ - │ Database │ - │ (Record) │ - └──────────┘ -``` +Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method. + +### Business Logic MUST Live in Commands + +All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build -> check -> execute pattern. + +### Path Resolution + +- `{% render 'blog_posts/card' %}` -> `app/views/partials/blog_posts/card.liquid` +- `{% function r = 'commands/blog_posts/create' %}` -> `app/lib/commands/blog_posts/create.liquid` +- `{% function r = 'queries/blog_posts/search' %}` -> `app/lib/queries/blog_posts/search.liquid` + +The `lib/` prefix is implicit in `function` calls — do NOT include it. -### Key Terminology +### Separation of Concerns -| Term | Definition | -|------|------------| -| **Instance** | A deployed environment (staging, production) | -| **Table** | Schema definition for data objects | -| **Record** | Individual data object instance | -| **Property** | Field/column definition | -| **Page** | Route handler + view template | -| **Layout** | Wrapper template for pages | -| **Partial** | Reusable template snippet | -| **Form** | Configuration for data submission | -| **Authorization Policy** | Access control rule | +- UI (Liquid templates) MUST be in partials and layouts +- Data operations (GraphQL) MUST be in query/mutation files +- Logic (commands) MUST be in `app/lib/commands/` + +### Modules First + +Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic. + +### Generators First (DEPRECATED — DO NOT USE) + +You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available. --- -## 4. Pages & Layouts +## 4. Pages -### Page Configuration +Pages are controllers — they handle routing, fetch data, and delegate to partials. -Pages are defined in `app/views/pages/` with `.liquid` extension. URL path is derived from file location unless `slug` is specified. +### Front Matter -**File:** `app/views/pages/blog/post.html.liquid` ```liquid --- -slug: blog/:slug -layout: blog_layout -converter: markdown -authorization_policies: - - valid_user_policy +slug: products/:id +method: post +layout: application +metadata: + title: "Product Details" --- - -

{{ context.params.slug }}

-

Author: {{ context.current_user.email }}

``` -### Page Configuration Options +**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** -| Option | Type | Description | -|--------|------|-------------| -| `slug` | String | URL pattern (e.g., `products/:id`) | -| `layout` | String | Layout template name | -| `converter` | String | `markdown`, `textile` | -| `authorization_policies` | Array | Policies to check | -| `response_headers` | Hash | Custom HTTP headers | -| `method` | String | HTTP method restriction | +| Property | Default | Notes | +|----------|---------|-------| +| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | +| `method` | `get` | `get`, `post`, `put`, `delete` | +| `layout` | `application` | Empty string for no layout | -### Dynamic URL Parameters +### Dynamic Routes -```yaml -# Required parameter -slug: products/:id -# Access: context.params.id +| Pattern | URL | `context.params` | +|---------|-----|------------------| +| `products/:id` | `/products/123` | `{ "id": "123" }` | +| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` | +| `search(/:q)` | `/search/books` | `{ "q": "books" }` | -# Optional parameter -slug: search(/:country)(/:city) -# Matches: /search, /search/USA, /search/USA/NYC +### REST CRUD Convention -# Wildcard parameter -slug: docs/*path -# Access: context.params.path (contains full remaining path) +| HTTP Method | URL Slug | Page File | GraphQL | Purpose | +|-------------|----------|-----------|---------|---------| +| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form | +| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource | +| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource | +| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form | +| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource | +| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource | +| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources | -# Optional wildcard -slug: docs(/*path) -# Matches: /docs and /docs/anything/here -``` +### CSRF Protection -### Layouts +Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous). -**File:** `app/views/layouts/application.liquid` -```liquid - - - - {{ page_title | default: 'My App' }} - {{ content_for_head }} - - - {% render 'header' %} - -
- {{ content_for_layout }} -
- - {% render 'footer' %} - - -``` - -**Key Layout Variables:** -- `content_for_layout` - Page content injection point -- `content_for_head` - Head content (meta tags, styles) - -### Context Object (Complete Reference) - -The `context` object is the **only predefined global object** in platformOS Liquid. It is available in pages, partials, layouts, and notifications. - -#### Authentication & User +### GET Page Example ```liquid -{{ context.current_user }} # Current user object or null -{{ context.current_user.id }} # User UUID -{{ context.current_user.email }} # User email -{{ context.current_user.first_name }}# First name -{{ context.current_user.last_name }} # Last name -{{ context.current_user.slug }} # User slug -{{ context.current_user.properties }}# Custom properties hash +--- +slug: articles/:id +method: get +--- +{% liquid + function article = 'queries/articles/find', id: context.params.id + + if article == blank + render '404' + break + endif + + render 'articles/show', article: article +%} ``` -#### Request Data +### POST Page Example ```liquid -{{ context.params }} # URL params + query string + form data -{{ context.params.id }} # Named route parameter -{{ context.params.page }} # Query string parameter -{{ context.headers }} # HTTP headers hash -{{ context.headers.REQUEST_METHOD }} # GET, POST, etc. -{{ context.headers.PATH_INFO }} # Request path -{{ context.cookies }} # Cookies hash -{{ context.session }} # Session data hash +--- +slug: articles +method: post +--- +{% liquid + function result = 'commands/articles/create', object: context.params.article + + if result.valid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname + redirect_to '/articles' + else + render 'articles/new', result: result + endif +%} ``` -#### Security +--- + +## 5. Partials & Layouts + +### Partials + +Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`). + +Partials MUST NOT have underscore-prefixed filenames. + +The render path maps: `render 'path/name'` -> `app/views/partials/path/name.liquid`. + +### Layouts + +The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout. + +--- + +## 6. Commands (Business Logic) + +All business logic MUST be encapsulated in commands following the build -> check -> execute pattern. + +### Main Command ```liquid -{{ context.authenticity_token }} # CSRF token for forms -{{ context.constants }} # Sensitive config (API keys, secrets) +{% doc %} + @param object {object} - Article data +{% enddoc %} + +{% liquid + function object = 'commands/articles/create/build', object: object + function object = 'commands/articles/create/check', object: object + + if object.valid + function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object + endif + + return object +%} ``` -**Accessing Constants:** +### Build Stage + +Normalizes and structures input data: + ```liquid -{{ context.constants.STRIPE_API_KEY }} -{{ context.constants.SENDGRID_API_KEY }} -``` +{% doc %} + @param object {object} - form params +{% enddoc %} -Set constants via GraphQL: -```graphql -mutation { - constant_set(name: "STRIPE_API_KEY", value: "sk_live_...") -} +{% liquid + assign object['title'] = object.title + assign object['body'] = object.body + + return object +%} ``` -#### Device & Environment +### Check Stage + +Validates the built object: ```liquid -{{ context.device }} # Device detection hash -{{ context.device.device_type }} # desktop, smartphone, tablet, etc. -{{ context.device.browser }} # Browser name -{{ context.device.os }} # Operating system -{{ context.environment }} # "staging" or "production" +{% doc %} + @param object {object} - form params +{% enddoc %} + +{% liquid + assign c = '{ "errors": {}, "valid": true }' | parse_json + + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title' + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body' + + assign object = object | hash_merge: valid: c.valid, errors: c.errors + + return object +%} ``` -#### Flash Messages +### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE) + +> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`). ```liquid -{{ context.flash }} # Flash messages hash -{{ context.flash.notice }} # Success message -{{ context.flash.alert }} # Error message -``` - -**Available Device Types:** -- `desktop` -- `smartphone` -- `tablet` -- `console` -- `portable media player` -- `tv` -- `car browser` -- `camera` - -**Available HTTP Headers:** -- `SERVER_NAME` -- `REQUEST_METHOD` -- `PATH_INFO` -- `REQUEST_URI` -- `HTTP_AUTHORIZATION` +{% comment %} WRONG — these partials do not exist: {% endcomment %} +{% function object = 'modules/core/commands/build', object: object %} +{% function object = 'modules/core/commands/check', object: object, + validators: '[{"name": "presence", "property": "title"}]' +%} ---- +{% comment %} CORRECT — only execute is shared: {% endcomment %} +{% if object.valid %} + {% function object = 'modules/core/commands/execute', + mutation_name: 'products/create', selection: 'record', object: object + %} +{% endif %} -## 5. Records & Tables +{% return object %} +``` -### Defining Tables +### Events -Tables define data structure in `app/schema/` as YAML files. +```liquid +{% comment %} Publish an event {% endcomment %} +{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %} -**File:** `app/schema/blog_post.yml` -```yaml -name: blog_post -properties: - - name: title - type: string - - name: content - type: text - - name: published_at - type: datetime - - name: author_id - type: string - - name: tags - type: array - - name: metadata - type: jsonb +{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %} +{% graphql _ = 'emails/send_confirmation', email: event.object.email %} ``` -### Property Types Reference +All inputs MUST be validated in commands before persisting. -| Type | Description | Liquid Equivalent | -|------|-------------|-------------------| -| `string` | Short text (255 chars) | String | -| `text` | Long text | String | -| `integer` | Whole numbers | Integer | -| `float` | Decimal numbers | Float | -| `boolean` | true/false | Boolean | -| `date` | Date only | Date | -| `datetime` | Date + Time | DateTime | -| `array` | List of values | Array | -| `jsonb` | JSON data | Hash | -| `geojson` | Geographic data | GeoJSON Object | -| `upload` | File attachment | Upload Object | +--- -### Record Lifecycle +## 7. GraphQL -``` -┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ -│ Create │───▶│ Read │───▶│ Update │───▶│ Delete │ -│ record │ │ record │ │ record │ │ record │ -└─────────┘ └─────────┘ └─────────┘ └─────────┘ - │ │ │ │ - GraphQL GraphQL GraphQL GraphQL - mutation query mutation mutation +GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively. + +### Query Wrapper Pattern + +```liquid +{% doc %} + @param id {string} - Article ID +{% enddoc %} + +{% liquid + graphql result = 'articles/find', id: id + return result.records.results | first +%} ``` -### Creating Records via GraphQL +### Search with Pagination -**File:** `app/graphql/records/create_blog_post.graphql` ```graphql -mutation create_blog_post( - $title: String! - $content: String! - $author_id: String! -) { - record_create( - record: { - table: "blog_post" - properties: [ - { name: "title", value: $title } - { name: "content", value: $content } - { name: "author_id", value: $author_id } - ] +query search($page: Int = 1, $keyword: String) { + records( + page: $page + per_page: 20 + filter: { + table: { value: "article" } + properties: [{ name: "title", contains: $keyword }] } + sort: { created_at: { order: DESC } } ) { - id - created_at - properties + total_pages + results { + id + title: property(name: "title") + body: property(name: "body") + } } } ``` -### Querying Records +All list queries MUST support `per_page` and `page` arguments for pagination. + +### Find by ID -**File:** `app/graphql/records/get_blog_posts.graphql` ```graphql -query get_blog_posts( - $limit: Int = 10 - $published: Boolean = true -) { +query find($id: ID!) { records( - per_page: $limit + per_page: 1 filter: { - table: { value: "blog_post" } - properties: [ - { name: "published", value_boolean: $published } - ] + id: { value: $id } + table: { value: "article" } } - sort: [{ created_at: { order: DESC } }] ) { results { id - created_at - properties + title: property(name: "title") } - total_entries - total_pages } } ``` -### CRUD Operations Summary - -| Operation | GraphQL | Example | -|-----------|---------|---------| -| Create | `record_create` | Create new record | -| Read | `records`, `record` | Query records | -| Update | `record_update` | Modify existing | -| Delete | `record_delete` | Soft/hard delete | - ---- - -## 6. Properties +### Related Records (Avoids N+1) -### Property Configuration +```graphql +results { + id + # belongs-to (single) + author: related_record(table: "user", join_on_property: "user_id") { + email + } + # has-many + comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") { + body: property(name: "body") + } +} +``` -Properties are defined in Table YAML files: +### Upload Property -```yaml -properties: - - name: status - type: string - default: draft - - - name: view_count - type: integer - default: 0 - - - name: settings - type: jsonb - - - name: tags - type: array +```graphql +image: property_upload(name: "image") { url } ``` -### Array Properties +### Mutations -Arrays can store multiple values of any type: +All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`: -```yaml -properties: - - name: tags - type: array -``` +- `record: record_create(record: { table: "...", properties: [...] }) { id }` +- `record: record_update(id: $id, record: { properties: [...] }) { id }` +- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table" -**GraphQL mutation:** +### Soft Delete vs Hard Delete + +**Soft delete** (default) — sets `deleted_at` timestamp: ```graphql mutation { - record_create( - record: { - table: "blog_post" - properties: [ - { name: "tags", value_array: ["tech", "news", "featured"] } - ] - } - ) { + record_delete(table: "article", id: "123") { id + deleted_at # Timestamp is set } } ``` -### JSONB Properties - -Store complex nested data: - -```yaml -properties: - - name: metadata - type: jsonb +**Hard delete** (permanent) — requires `hard_delete: true`: +```graphql +mutation { + record_delete(table: "article", id: "123", hard_delete: true) { + id + } +} ``` -**GraphQL mutation:** +Soft-deleted records can be queried using the `deleted_at` filter: ```graphql -mutation { - record_create( - record: { - table: "blog_post" - properties: [ - { - name: "metadata", - value_json: "{\"seo_title\": \"My Post\", \"keywords\": [\"a\", \"b\"]}" - } - ] +query { + records( + filter: { + table: { value: "article" } + deleted_at: { exists: true } } ) { - id + results { id deleted_at } } } ``` -### Upload Properties +### Pagination Component + +```liquid +{% graphql result = 'products/search', page: context.params.page %} +{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %} +``` + +--- + +## 8. Schema -Handle file uploads: +Schema files define database tables in YAML at `app/schema/`. ```yaml +# app/schema/article.yml +name: article properties: - - name: avatar + - name: title + type: string + - name: body + type: text + - name: published_at + type: datetime + - name: image type: upload + options: + public: true + versions: + - name: thumbnail + resize: "200x200>" + - name: medium + resize: "800x600>" ``` -**In forms:** -```liquid -{% form %} - - -{% endform %} -``` - ---- +### Property Types -## 7. Forms +`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload` -### Form Structure +### Upload Options -Forms have two sections: YAML configuration + Liquid implementation. +| Option | Type | Description | +|--------|------|-------------| +| `public` | boolean | `true` = public URL, `false` = requires auth | +| `max_size` | integer | Max file size in bytes | +| `versions` | array | Image resize versions | +| `extensions` | array | Allowed file extensions | + +Version resize syntax: +- `100x100>` — Resize only if larger (downscale only) +- `100x100<` — Resize only if smaller (upscale only) +- `100x100#` — Exact dimensions (may crop) +- `100x100^` — Minimum dimensions (may crop) +- `100x100` — Fit within dimensions + +### Reserved Names (MUST NOT Use) + +The following names are reserved by platformOS and MUST NOT be used as custom table or property names: + +**System fields (automatically created on every record):** +- `id` — Record UUID +- `created_at` — Creation timestamp +- `updated_at` — Last update timestamp +- `deleted_at` — Soft delete timestamp +- `type_name` — Table name +- `properties` — Property container + +**Reserved table names:** +- `user`, `users` — Built-in User table +- `session`, `sessions` — Session management +- `record`, `records` — Record operations +- `constant`, `constants` — System constants +- `table`, `tables` — Table metadata +- `background_job`, `background_jobs` — Background job system -**File:** `app/forms/contact_form.liquid` -```liquid ---- -name: contact_form -resource: contact_message -resource_owner: anyone -redirect_to: /contact/thank-you -flash_notice: Message sent successfully! -fields: - properties: - name: - validation: - presence: true - email: - validation: - presence: true - email: true - message: - validation: - presence: true - length: - minimum: 10 -email_notifications: - - contact_notification -authorization_policies: - - not_spam_policy --- -{% form %} -
- - - {% if form.fields.properties.name.errors %} - {{ form.fields.properties.name.errors }} - {% endif %} -
- -
- - -
- -
- - -
- - -{% endform %} -``` +## 9. Liquid Reference -### Form Configuration Options +### Tags -| Option | Description | -|--------|-------------| -| `name` | Unique form identifier | -| `resource` | Associated table name | -| `resource_owner` | `anyone`, `self`, `anyone_with_token` | -| `redirect_to` | URL after successful submission | -| `flash_notice` | Success message | -| `flash_alert` | Error message | -| `fields` | Field definitions and validation | -| `email_notifications` | Emails to send | -| `api_call_notifications` | API calls to make | -| `callback_actions` | Synchronous Liquid code | -| `async_callback_actions` | Background job code | -| `authorization_policies` | Access control | -| `default_payload` | JSON payload to merge | +```liquid +{% graphql result = 'query_name', arg: value %} +{% function result = 'path/to/partial', arg: value %} +{% render 'partial', var: value %} +{% doc %} @param name {Type} - description {% enddoc %} +{% return result %} +{% export my_var, namespace: 'my_ns' %} +{% parse_json data %}{"key": "value"}{% endparse_json %} +{% redirect_to '/path', status: 302 %} +{% session key = value %} +{% log variable, type: 'debug' %} +{% cache key: 'key_name', expire: 3600 %}...{% endcache %} +{% background source_name: 'job_name', priority: 'low', delay: 5.0, max_attempts: 3 %}...{% endbackground %} +{% content_for_layout %} +{% theme_render_rc 'modules/common-styling/toasts' %} +``` -### Validation Options +**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is). -```yaml -fields: - properties: - email: - validation: - presence: - message: Email is required - email: true - uniqueness: - message: Email already exists - password: - validation: - length: - minimum: 8 - message: Password too short - confirmation: true # Requires password_confirmation field - age: - validation: - numericality: - greater_than: 0 - less_than: 150 - website: - validation: - url: true +### Output + +```liquid +{{ variable }} +{{ variable | html_safe }} +{% print variable %} ``` -### Rendering Forms in Pages +### Common Filters -```liquid ---- -slug: contact ---- +- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by` +- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys` +- **Dates:** `add_to_time`, `localize`, `is_date_in_past` +- **Validation:** `is_email_valid`, `is_json_valid` +- **Encoding:** `json`, `base64_encode`, `url_encode` -

Contact Us

+### Coding Standards -{% render_form 'contact_form' %} +You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line. - -
- {% render_form 'contact_form', class: 'contact-form' %} -
+**Correct:** +```liquid +{% liquid + assign filtered = products | where: 'available', true | map: 'title' | first + assign price = product | where: 'id', pid | map: 'price' | first +%} ``` -### Form Object Structure - +**WRONG (causes syntax errors):** ```liquid -{{ form.fields.properties.FIELD_NAME.name }} # Input name attribute -{{ form.fields.properties.FIELD_NAME.value }} # Current value -{{ form.fields.properties.FIELD_NAME.errors }} # Validation errors -{{ form.errors }} # All form errors -{{ form.valid? }} # Boolean validation state +{% liquid + assign filtered = products + | where: 'available', true + | map: 'title' + | first +%} ``` --- -## 8. Liquid Templating +## 10. Global Context -### platformOS Liquid Tags +**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results. -#### Query Tag (GraphQL Execution) - -```liquid -{% graphql my_query = 'get_blog_posts', limit: 10 %} +| Property | Description | +|----------|-------------| +| `context.params` | HTTP parameters (query string + body) | +| `context.session` | Server-side session storage | +| `context.location` | URL info (`pathname`, `search`, `host`) | +| `context.environment` | `staging` or `production` | +| `context.is_xhr` | `true` for AJAX requests | +| `context.authenticity_token` | CSRF token | +| `context.constants` | Environment constants (hidden from `{{ context }}` for security) | +| `context.page.metadata` | Page metadata from front matter | -{% for post in my_query.records.results %} -

{{ post.properties.title }}

-{% endfor %} -``` +### context.current_user -#### Background Tag (Async Jobs) +`context.current_user` is a documented platformOS object that returns basic data of the currently logged-in user: ```liquid -{% background job_id = 'send_email', delay: 0.5, priority: 'high', max_attempts: 3 %} - {% graphql result = 'send_notification', user_id: user_id %} - {% log result %} -{% endbackground %} +{{ context.current_user.id }} # User UUID +{{ context.current_user.email }} # User email +{{ context.current_user.first_name }} # First name +{{ context.current_user.last_name }} # Last name +{{ context.current_user.slug }} # User slug +{{ context.current_user.properties }} # Custom properties hash ``` -**Background Options:** -- `delay`: Minutes to delay (default: 0) -- `priority`: `low`, `default`, `high` -- `max_attempts`: 1-5 retries (default: 1) -- `source_name`: Job identifier label +Returns `null` if no user is logged in. -**CRITICAL:** Variables must be explicitly passed to background: -```liquid -{% background data: my_data, user_id: user.id %} - {{ data }} {# Available #} - {{ my_data }} {# NOT available - wasn't passed #} -{% endbackground %} -``` +For projects using pos-module-user, prefer `modules/user/queries/user/current` as it provides additional normalized user data and role information. Use `context.current_user` for simple checks (e.g., checking if anyone is logged in) and the User Module query for full user data operations. -#### Include/Render Tags +--- -```liquid -{# Include with local variables #} -{% include 'header', title: 'My Page', show_nav: true %} +## 11. User Module (Authentication & Authorization) -{# Render (preferred - isolated scope) #} -{% render 'product_card', product: product %} +You MUST use the User Module for all authentication and authorization. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. -{# Render with collection #} -{% render 'product_card' for products as product %} -``` +### Built-in Roles + +- **Anonymous** — unauthenticated users +- **Authenticated** — any logged-in user +- **Superadmin** — bypasses ALL permission checks -#### Function Tag +### Authorization Helpers ```liquid -{% function my_result = 'helpers/calculate_total', items: cart_items %} +{% function profile = 'modules/user/queries/user/current' %} -{# In app/views/partials/helpers/calculate_total.liquid #} -{% return items | sum: 'price' %} +{% comment %} Check permission (returns true/false) {% endcomment %} +{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %} + +{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %} + +{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %} ``` -#### Parse JSON Tag +> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`. -```liquid -{% parse_json my_data %} - { - "name": "John", - "items": [1, 2, 3] - } -{% endparse_json %} - -{{ my_data.name }} {# John #} -``` - -#### Cache Tag +### Custom Permissions -Cache expensive operations to improve performance: +Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`: -```liquid -{% cache key: 'sidebar_categories', expire: 3600 %} - {% graphql categories = 'get_categories' %} - {% for category in categories.records.results %} - {{ category.properties.name }} - {% endfor %} -{% endcache %} +```bash +mkdir -p app/modules/user/public/lib/queries/role_permissions +cp modules/user/public/lib/queries/role_permissions/permissions.liquid \ + app/modules/user/public/lib/queries/role_permissions/permissions.liquid ``` -**Cache Options:** -- `key` - Unique cache identifier -- `expire` - Cache lifetime in seconds -- `if` - Conditional caching - +Define roles: ```liquid -{% cache key: 'user_stats', expire: 300, if: context.current_user %} - {# Only cache for logged-in users #} -{% endcache %} +{% parse_json data %} +{ + "admin": ["admin.view", "users.manage"], + "editor": ["article.create", "article.update"], + "superadmin": [] +} +{% endparse_json %} +{% return data %} ``` -#### Log Tag +### Native Authorization Policies (Optional) -Debug by logging to instance logs: +platformOS also provides `authorization_policies/` for page and form-level access control. These work independently of the User Module and are useful for simple checks: +**File:** `app/authorization_policies/requires_login.liquid` ```liquid -{% log 'Debug message' %} -{% log user_id: user.id, action: 'purchase' %} -{% log my_variable %} +--- +name: requires_login +redirect_to: /sign-in +flash_alert: Please sign in to access this page +--- +{% if context.current_user %}true{% else %}false{% endif %} ``` -View logs with: `pos-cli logs staging` - -#### Content For Tag - -Inject content into layouts: - +**Usage in page front matter:** ```liquid -{# In page #} -{% content_for 'head' %} - - -{% endcontent_for %} - -{# In layout #} - - {{ content_for_head }} - +--- +slug: admin/dashboard +authorization_policies: + - requires_login +--- ``` -#### Yield Tag +For projects using pos-module-user, prefer the module's authorization helpers. Use native authorization policies only for simple use cases not covered by the module. -Define content blocks in layouts: - -```liquid -{# In layout #} - - -{# In page #} -{% content_for 'sidebar' %} -
-

Related Links

-
-{% endcontent_for %} -``` +--- -#### Return Tag +## 12. Core Module -Return values from function partials: +You MUST use pos-module-core for commands, events, and validators. -```liquid -{# app/views/partials/calculate_tax.liquid #} -{% assign tax = amount | times: 0.2 %} -{% return tax %} +--- -{# Usage #} -{% function tax_amount = 'calculate_tax', amount: 100 %} -Tax: {{ tax_amount }} -``` +## 13. Common Styling -#### Raw Tag +You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components. -Prevent Liquid from processing content: +### Setup ```liquid -{% raw %} - {{ this will not be processed }} - {% if true %}neither will this{% endif %} -{% endraw %} +{% comment %} In {% endcomment %} +{% render 'modules/common-styling/init' %} +``` +```html + ``` -#### Liquid Tag (New Syntax) - -Use the new Liquid tag syntax for cleaner code: +### File Upload Component ```liquid -{% liquid - assign user = context.current_user - if user - echo 'Hello, ' | append: user.first_name - else - echo 'Hello, Guest' - endif +{% render 'modules/common-styling/forms/upload', + id: 'image', presigned_upload: presigned, name: 'image', + allowed_file_types: ['image/*'], max_number_of_files: 5 %} ``` -### Complete platformOS Tag Reference - -| Tag | Purpose | -|-----|---------| -| `{% graphql %}` | Execute GraphQL queries | -| `{% background %}` | Run async background jobs | -| `{% form %}` | Render form with CSRF protection | -| `{% render_form %}` | Include a form by name | -| `{% include %}` | Include partial (deprecated, use render) | -| `{% render %}` | Render partial with isolated scope | -| `{% function %}` | Call function partial with return value | -| `{% parse_json %}` | Parse JSON string to object | -| `{% cache %}` | Cache content fragment | -| `{% log %}` | Log to instance logs | -| `{% content_for %}` | Define content for layout blocks | -| `{% yield %}` | Insert content block in layout | -| `{% return %}` | Return value from function | -| `{% raw %}` | Disable Liquid processing | -| `{% liquid %}` | New multi-line Liquid syntax | - -### platformOS Liquid Filters - -#### Array Filters - -```liquid -{# Add to array #} -{% assign new_array = old_array | add_to_array: 'new_item' %} - -{# Compact - remove nil values #} -{% assign clean = array | compact %} - -{# Group by property #} -{% assign grouped = products | group_by: 'category' %} - -{# Map/extract property #} -{% assign names = users | map: 'name' %} +--- -{# Sort by property #} -{% assign sorted = products | sort_by: 'price' %} +## 14. Translations (i18n) -{# Sum array values #} -{{ order_items | sum: 'total' }} +You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. +The YAML file requires top-level language key: -{# Find unique values #} -{% assign unique_tags = all_tags | uniq %} ``` - -#### Date/Time Filters - -```liquid -{{ 'now' | to_time }} -{{ '2024-01-15' | to_time | add_to_time: 1, 'week' }} -{{ 'now' | strftime: '%Y-%m-%d %H:%M' }} -{{ post.created_at | time_ago_in_words }} +en: + app: + contact_form: + title: "..." ``` -#### Hash/Object Filters - -```liquid -{# Merge hashes #} -{% assign combined = defaults | hash_merge: overrides %} +--- -{# Get keys #} -{% assign keys = config | hash_keys %} +## 15. Forms -{# Get values #} -{% assign values = config | hash_values %} +You MUST use HTML `` tags. You MUST NOT use `{% form %}`. -{# Deep clone #} -{% assign copy = original | deep_clone %} +Forms MUST include the CSRF token: +```html + ``` -#### URL Filters - -```liquid -{{ 'style.css' | asset_url }} -{{ 'photo.jpg' | asset_url | img_tag: 'Photo' }} -{{ user.avatar | default: 'default.png' | asset_url }} +For PUT/DELETE, forms MUST use POST with a `_method` hidden field: +```html + + + + + ``` -#### String Filters - -```liquid -{{ text | strip_html }} -{{ text | truncate: 100 }} -{{ text | truncatewords: 20 }} -{{ text | url_encode }} -{{ text | url_decode }} -{{ text | md5 }} -{{ text | sha1 }} -{{ text | hmac_sha256: secret_key }} -{{ text | base64_encode }} -{{ text | base64_decode }} -{{ text | html_safe }} {# Mark as safe HTML #} -{{ text | sanitize }} {# Sanitize HTML input #} -{{ text | escape_javascript }} {# Escape for JS #} -{{ text | json }} {# Convert to JSON #} -``` - -#### Number/Currency Filters - -```liquid -{{ 1234.5 | round }} {# 1235 #} -{{ 1234.5 | round: 1 }} {# 1234.5 #} -{{ 1234.5 | ceil }} {# 1235 #} -{{ 1234.5 | floor }} {# 1234 #} -{{ 19.99 | amount_to_fractional: 'USD' }} {# 1999 (cents) #} -{{ 1999 | fractional_to_amount: 'USD' }} {# 19.99 #} -{{ 1234567 | format_number: 'en' }} {# 1,234,567 #} +Form fields MUST use bracket notation for resource binding: +```html + ``` -#### Encoding/Encryption Filters +Access in page: `context.params.resource` -```liquid -{{ 'text' | base64_encode }} -{{ 'ZW5jb2RlZA==' | base64_decode }} -{{ 'text' | md5 }} -{{ 'text' | sha1 }} -{{ 'text' | hmac_sha256: secret_key }} -{{ 'text' | encrypt: key, algorithm: 'aes-256-gcm' }} -{{ 'encrypted' | decrypt: key, algorithm: 'aes-256-gcm' }} -``` +HTML forms submit checkbox values as "on" (string), but GraphQL expects boolean field to be Boolean type, not string. -**Supported Encryption Algorithms:** -- `aes-128-cbc`, `aes-192-cbc`, `aes-256-cbc` -- `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm` -- `aes-128-ctr`, `aes-192-ctr`, `aes-256-ctr` -- And many more... +### Form Configurations (app/forms/) -#### URL/Link Filters +platformOS also supports form configurations in `app/forms/` that define validation, callbacks, and processing. These are YAML + Liquid files: ```liquid -{{ 'style.css' | asset_url }} -{{ 'photo.jpg' | asset_url | img_tag: 'Alt text' }} -{{ 'photo.jpg' | asset_url | img_tag: 'Alt', 'class-name' }} -{{ '/path' | link_to: 'Click here' }} -{{ 'page' | app_url }} {# Generate app URL #} -``` - -#### Debug/Development Filters +--- +name: contact_form +resource: contact_message +resource_owner: anyone +redirect_to: /contact/thank-you +flash_notice: Message sent successfully! +fields: + properties: + name: + validation: + presence: true + email: + validation: + presence: true + email: true +--- -```liquid -{{ variable | debug }} {# Debug output #} -{{ variable | inspect }} {# Ruby-style inspect #} -{{ 'code' | time_diff }} {# Measure execution time #} +{% form %} + + + +{% endform %} ``` -### Complete platformOS Filter Reference +The `{% form %}` tag automatically generates the `
` element with correct attributes and CSRF token. It also provides the `form` object with field metadata. -| Category | Filters | -|----------|---------| -| **Array** | `add_to_array`, `compact`, `group_by`, `map`, `sort_by`, `sum`, `uniq`, `flatten`, `shuffle`, `rotate`, `in_groups_of` | -| **Date** | `to_time`, `add_to_time`, `strftime`, `time_ago_in_words`, `date_add` | -| **Hash** | `hash_merge`, `hash_keys`, `hash_values`, `deep_clone` | -| **String** | `strip_html`, `truncate`, `truncatewords`, `url_encode`, `md5`, `sha1`, `hmac_sha256`, `base64_encode`, `sanitize`, `html_safe` | -| **Number** | `round`, `ceil`, `floor`, `format_number`, `amount_to_fractional`, `fractional_to_amount` | -| **URL** | `asset_url`, `img_tag`, `link_to`, `app_url` | -| **JSON** | `json`, `parse_json` | -| **Debug** | `debug`, `inspect`, `time_diff` | +When using the Core Module command pattern (recommended), use HTML forms with bracket notation. The `{% form %}` tag is available for simpler use cases. -### Whitespace Control +### Form Validation Error Display ```liquid -{# Use hyphens to control whitespace #} -{%- if condition -%} - No extra whitespace -{%- endif -%} - -{# Output whitespace control #} -{{- variable -}} +{% if form.fields.properties.name.errors %} + {{ form.fields.properties.name.errors }} +{% endif %} ``` ---- - -## 9. GraphQL API +### Validation Types -### Query Structure +| Validation | Description | +|------------|-------------| +| `presence: true` | Field is required | +| `email: true` | Must be valid email format | +| `uniqueness: true` | Must be unique across records | +| `length: { minimum: 5, maximum: 100 }` | String length constraints | +| `numericality: { greater_than: 0 }` | Numeric range constraints | +| `confirmation: true` | Must match `_confirmation` field | +| `url: true` | Must be valid URL | -All GraphQL queries are stored in `app/graphql/` with `.graphql` extension. - -### Record Queries - -**List Records:** -```graphql -query list_products( - $page: Int = 1 - $per_page: Int = 20 - $category: String -) { - records( - per_page: $per_page - page: $page - filter: { - table: { value: "product" } - properties: [ - { name: "category", value: $category } - ] - } - sort: [{ price: { order: ASC } }] - ) { - total_entries - total_pages - has_next_page - has_previous_page - results { - id - created_at - updated_at - deleted_at - type_name - properties - } - } -} -``` +--- -**Single Record:** -```graphql -query get_product($id: ID!) { - record(id: $id) { - id - properties - } -} -``` +## 16. Constants & Credentials -### Record Mutations +You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`. -**Create:** -```graphql -mutation create_product( - $name: String! - $price: Float! -) { - record_create( - record: { - table: "product" - properties: [ - { name: "name", value: $name } - { name: "price", value_float: $price } - ] - } - ) { - id - properties - errors { - message - } - } -} -``` +### Setting Constants -**Update:** -```graphql -mutation update_product( - $id: ID! - $name: String -) { - record_update( - id: $id - record: { - properties: [ - { name: "name", value: $name } - ] - } - ) { - id - properties - } -} +**Via CLI:** +```bash +pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev +pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev +pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev ``` -**Delete:** +**Via GraphQL:** ```graphql -mutation delete_product($id: ID!) { - record_delete(id: $id) { - id - deleted_at +mutation { + constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") { + name } } ``` -### User Queries - -```graphql -# Get current user -query current_user { - current_user { - id - email - created_at - properties - } -} - -# List users -query list_users { - users { - results { - id - email - properties - } - } -} +### Accessing Constants in Liquid -# Create user -mutation create_user( - $email: String! - $password: String! -) { - user_create( - user: { - email: $email - password: $password - } - ) { - id - email - } -} +Constants are hidden from `{{ context }}` for security. You MUST access them explicitly: +```liquid +{{ context.constants.STRIPE_SK_KEY }} +{{ context.constants.API_BASE_URL }} ``` -### Pagination - -```graphql -query paginated_records( - $page: Int = 1 - $per_page: Int = 20 -) { - records( - page: $page - per_page: $per_page - filter: { table: { value: "post" } } - ) { - total_entries - total_pages - has_next_page - has_previous_page - results { id } - } -} -``` +### Naming Conventions -### Filtering +| Use Case | Example | +|----------|---------| +| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` | +| API URLs | `API_BASE_URL` | +| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` | -```graphql -query filtered_records { - records( - filter: { - table: { value: "product" } - properties: [ - { name: "status", value: "active" } - { name: "price", range: { gte: 10, lte: 100 } } - ] - created_at: { gte: "2024-01-01" } - } - ) { - results { id } - } -} -``` +Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically. --- -## 10. Users & Authentication - -### User Properties +## 17. Flash Messages & Toasts -Define custom user properties in `app/user.yml`: +### Layout Setup (before ``) -```yaml -properties: - - name: role - type: string - default: customer - - name: first_name - type: string - - name: last_name - type: string - - name: last_sign_in_at - type: datetime +```liquid +{% liquid + function flash = 'modules/core/commands/session/get', key: 'sflash' + if context.location.pathname != flash.from or flash.force_clear + function _ = 'modules/core/commands/session/clear', key: 'sflash' + endif + render 'modules/common-styling/toasts', params: flash +%} ``` -### Built-in User Fields +### Liquid Usage -| Field | Description | -|-------|-------------| -| `email` | Unique identifier (case-insensitive) | -| `password` | Virtual field (bcrypt2 hashed) | -| `encrypted_password` | Stored hash | -| `created_at` | Registration timestamp | -| `updated_at` | Last update timestamp | - -### Authentication Flow - -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Sign Up │────▶│ Sign In │────▶│ Session │ -│ (Form) │ │ (Form) │ │ (Cookie) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ - ┌──────┴──────┐ - ▼ ▼ - ┌──────────┐ ┌──────────┐ - │ Logout │ │ Access │ - │ (Form) │ │ Pages │ - └──────────┘ └──────────┘ +```liquid +{% liquid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname + redirect_to '/orders' +%} ``` -### Session Management - -```liquid -{# Check if user is logged in #} -{% if context.current_user %} -

Welcome, {{ context.current_user.email }}

-{% else %} - Sign In -{% endif %} +### JavaScript Usage -{# Access user properties #} -{{ context.current_user.properties.role }} -{{ context.current_user.properties.first_name }} +```javascript +new pos.modules.toast('success', 'Saved!'); +new pos.modules.toast('error', 'Failed'); ``` -### Sign In Form +--- + +## 18. Notifications (Email/SMS) -**File:** `app/forms/sign_in_form.liquid` ```liquid +{% comment %} app/emails/order_confirmation.liquid {% endcomment %} --- -name: sign_in_form -resource: session -resource_owner: anyone -redirect_to: / -flash_alert: Invalid email or password +to: {{ data.email }} +from: shop@example.com +subject: "Order #{{ data.order_id }}" +layout: mailer --- - -{% form %} - - - -{% endform %} +

Thank you for your order!

``` -### Sign Up Form +Emails SHOULD be sent asynchronously using events + consumers. -**File:** `app/forms/sign_up_form.liquid` -```liquid ---- -name: sign_up_form -resource: user -resource_owner: anyone -redirect_to: /welcome -flash_notice: Account created! -fields: - email: - validation: - presence: true - email: true - uniqueness: true - password: - validation: - presence: true - length: - minimum: 8 --- -{% form %} - - - -{% endform %} -``` +## 19. Payments (Stripe) ---- +### Install -## 11. Authorization Policies +```bash +pos-cli modules install payments && pos-cli modules install payments_stripe +pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev +``` -### Creating Policies +### Create Transaction -**File:** `app/authorization_policies/valid_user.liquid` ```liquid ---- -name: valid_user_policy -redirect_to: /sign-in -flash_alert: Please sign in to access this page ---- - -{% if context.current_user %} - true -{% else %} - false -{% endif %} +{% function transaction = 'modules/payments/commands/transactions/create', + gateway: 'stripe', email: email, line_items: items, + success_url: '/thank-you', cancel_url: '/cart' +%} +{% function url = 'modules/payments/queries/pay_url', transaction: transaction %} +{% redirect_to url, status: 303 %} ``` -### Policy Configuration - -| Option | Description | -|--------|-------------| -| `name` | Policy identifier | -| `redirect_to` | Where to redirect if policy fails | -| `flash_alert` | Error message on failure | +Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed` -### Associating with Pages +**Test card:** `4242 4242 4242 4242`, any future date, any CVC. -```liquid ---- -slug: admin/dashboard -authorization_policies: - - valid_user_policy - - admin_only_policy --- -``` -### Associating with Forms +## 20. Background Jobs -```liquid ---- -name: delete_product_form -resource: product -authorization_policies: - - valid_user_policy - - product_owner_policy ---- -``` +Background jobs run code asynchronously outside the HTTP request cycle. -### Common Policy Patterns +### Syntax -**Admin Only:** ```liquid -{% if context.current_user.properties.role == 'admin' %} - true -{% else %} - false -{% endif %} +{% background + source_name: 'send_welcome_email', + delay: 5.0, + priority: 'default', + max_attempts: 3 +%} + {% graphql user = 'users/find', id: user_id %} + {% graphql _ = 'emails/send_welcome', email: user.email %} +{% endbackground %} ``` -**Resource Owner:** -```liquid -{% graphql product = 'get_product', id: context.params.id %} -{% if product.record.properties.owner_id == context.current_user.id %} - true -{% else %} - false -{% endif %} -``` +### Parameters ---- +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `source_name` | String | — | Human-readable job identifier | +| `priority` | String | `default` | `high` (1min), `default` (5min), `low` (60min) | +| `delay` | Float | 0 | Minutes to delay execution | +| `max_attempts` | Integer | 1 | Retry count (1-5) | -## 12. Modules +### CRITICAL: Variable Scope -### Module Structure +Only variables **explicitly passed** to the background tag are available inside it. The `context` object is available by default but with limitations. -``` -modules/ -└── my_module/ - ├── public/ - │ ├── views/ - │ ├── forms/ - │ ├── graphql/ - │ └── assets/ - └── private/ - ├── views/ - └── forms/ +**WRONG:** +```liquid +{% assign user_id = context.current_user.id %} +{% background source_name: 'job' %} + {{ user_id }} {# nil — not passed #} +{% endbackground %} ``` -### Module Namespacing - -All module files are prefixed with `modules/MODULE_NAME/`: - +**CORRECT:** ```liquid -{# Reference module partial #} -{% render 'modules/my_module/header' %} - -{# Reference module GraphQL #} -{% graphql result = 'modules/my_module/get_data' %} - -{# Reference module form #} -{% render_form 'modules/my_module/contact_form' %} - -{# Reference module asset #} -{{ 'modules/my_module/style.css' | asset_url }} +{% assign user_id = context.current_user.id %} +{% background source_name: 'job', user_id: user_id %} + {{ user_id }} {# Works! Explicitly passed #} +{% endbackground %} ``` -### Installing Modules +### Priority Levels & Execution Limits -```bash -# Install from Partner Portal -pos-cli modules install module_name - -# Install specific version -pos-cli modules install module_name@1.2.3 -``` - -### Overwriting Module Files +| Priority | Max Execution | Use Case | +|----------|---------------|----------| +| `high` | 1 minute | Critical, time-sensitive tasks | +| `default` | 5 minutes | Standard operations | +| `low` | 60 minutes | Heavy processing, batch jobs | -Create a file with the same path in your `app` directory: - -``` -app/ -└── views/ - └── partials/ - └── modules/ - └── my_module/ - └── header.liquid # Overrides module version -``` - -### Creating Modules - -1. Create directory: `modules/MODULE_NAME/` -2. Add `public/` and/or `private/` subdirectories -3. Structure mirrors `app/` directory -4. Deploy with `pos-cli deploy` - ---- - -## 13. Background Jobs - -### When to Use Background Jobs - -| Use Case | Example | -|----------|---------| -| Email sending | Welcome emails, notifications | -| API calls | Webhooks, external integrations | -| Data processing | Imports, exports, reports | -| Scheduled tasks | Daily cleanup, reminders | -| Long operations | Image processing, batch updates | - -### Background Tag Syntax - -```liquid -{% background - job_id = 'unique_job_id', - delay: 5.0, # Delay in minutes - priority: 'high', # low, default, high - max_attempts: 3, # 1-5 retries - source_name: 'my_job' # Human-readable label -%} - {# Your async code here #} - {% graphql result = 'send_email', to: email %} - {% log result %} -{% endbackground %} -``` - -### Priority Levels - -| Priority | Max Execution | Use Case | -|----------|---------------|----------| -| `high` | 1 minute | Critical, time-sensitive | -| `default` | 5 minutes | Standard operations | -| `low` | 60 minutes | Background processing | - -### Variable Passing - -```liquid -{% assign user_id = context.current_user.id %} -{% assign data = '{"key": "value"}' | parse_json %} - -{% background user_id: user_id, data: data %} - {# Variables available: user_id, data, context #} - {% graphql user = 'get_user', id: user_id %} - {% log user %} -{% endbackground %} -``` - -**IMPORTANT:** Only explicitly passed variables are available inside background blocks. - -### Monitoring Jobs +### Monitoring Jobs ```graphql -query list_background_jobs { +query { background_jobs( - per_page: 10 + per_page: 20 sort: [{ created_at: { order: DESC } }] ) { results { @@ -1549,1343 +1177,180 @@ query list_background_jobs { max_attempts created_at started_at - completed_at - failed_at - error_message - } - } -} -``` - ---- - -## 14. Notifications - -### Email Notifications - -**File:** `app/emails/welcome_user.liquid` -```liquid ---- -name: welcome_user -to: '{{ form.email }}' -from: 'noreply@example.com' -subject: 'Welcome to Our Platform!' -layout: mailer ---- - -

Welcome, {{ form.name }}!

-

Thank you for joining us.

- -

Get Started

-``` - -**Email Configuration Options:** - -| Option | Description | -|--------|-------------| -| `name` | Notification identifier | -| `to` | Recipient email (Liquid) | -| `from` | Sender email | -| `subject` | Email subject (Liquid) | -| `layout` | Email layout template | -| `bcc` | BCC recipients | -| `cc` | CC recipients | - -### SMS Notifications - -**File:** `app/smses/verification_code.liquid` -```liquid ---- -name: verification_code -to: '{{ form.phone_number }}' ---- - -Your verification code is: {{ form.verification_code }} -``` - -### API Call Notifications - -**File:** `app/api_calls/webhook.liquid` -```liquid ---- -name: webhook_notification -to: 'https://api.example.com/webhook' -format: json -callback: '' -request_type: POST -headers: > - { - "Authorization": "Bearer {{ context.constants.api_key }}", - "Content-Type": "application/json" - } ---- - -{ - "event": "user_signup", - "user_id": "{{ form.id }}", - "email": "{{ form.email }}", - "timestamp": "{{ 'now' | to_time }}" -} -``` - -### Triggering Notifications - -From forms: -```yaml ---- -name: contact_form -email_notifications: - - contact_confirmation - - admin_notification -api_call_notifications: - - crm_webhook -sms_notifications: - - sms_confirmation ---- -``` - ---- - -## 15. Assets & Uploads - -### Assets (Static Files) - -Assets are files in `app/assets/` that are served via CDN. - -**Directory Structure:** -``` -app/assets/ -├── css/ -│ └── app.css -├── js/ -│ └── app.js -├── images/ -│ └── logo.png -└── fonts/ - └── custom.woff2 -``` - -**Using Assets:** -```liquid - - -Logo -``` - -### User Uploads - -Uploads are dynamic files stored per-record. - -**Table Definition:** -```yaml -name: product -properties: - - name: image - type: upload -``` - -**Form:** -```liquid -{% form %} - -{% endform %} -``` - -**Displaying Uploads:** -```liquid -{% graphql product = 'get_product', id: id %} -{{ product.record.properties.image.file_name }} -``` - -**Upload Properties:** - -| Property | Description | -|----------|-------------| -| `url` | Direct file URL | -| `file_name` | Original filename | -| `content_type` | MIME type | -| `size` | File size in bytes | - -### Assets vs Uploads - -| Aspect | Assets | Uploads | -|--------|--------|---------| -| Location | `app/assets/` | Record properties | -| Use Case | Static files (CSS, JS, logos) | Dynamic content | -| Quantity | Thousands expected | Millions supported | -| CDN | Yes | Yes | -| Max Size | 2GB | 2GB | - -### Direct S3 Upload - -platformOS uses **direct S3 upload** - files go straight to AWS S3 without passing through the application server. - -**Advantages:** -- **Speed** - No middleman, faster uploads -- **Cost** - Less bandwidth and server load -- **Security** - No file processing on app server -- **Scalability** - Handle unlimited concurrent uploads -- **Size** - Up to 5GB single file, 5TB multipart - -**Upload Flow:** -``` -1. User selects file -2. Browser requests signed S3 URL from platformOS -3. Browser uploads directly to S3 -4. S3 returns success -5. platformOS saves file reference to record -``` - -### Upload Configuration Options - -**Table Definition with Options:** -```yaml -name: product -properties: - - name: image - type: upload - options: - public: true # Public or private access - max_size: 5242880 # 5MB in bytes - versions: - - name: thumbnail - resize: '200x200>' # Resize to fit 200x200 - - name: medium - resize: '800x600>' - extensions: - - jpg - - png - - gif -``` - -### Upload Versions - -Automatically generate resized versions: - -```yaml -properties: - - name: photo - type: upload - options: - versions: - - name: thumb - resize: '100x100#' # Exact fit, may crop - - name: medium - resize: '300x300>' # Fit within, no upscale - - name: large - resize: '800x800>' -``` - -**Access versions in Liquid:** -```liquid -{{ product.properties.photo.url }} # Original -{{ product.properties.photo.versions.thumb.url }} # Thumbnail -{{ product.properties.photo.versions.medium.url }} # Medium -``` - -### Image Processing Options - -| Option | Description | Example | -|--------|-------------|---------| -| `resize: '100x100'` | Resize to dimensions | Fit within | -| `resize: '100x100>'` | Resize only if larger | Downscale only | -| `resize: '100x100<'` | Resize only if smaller | Upscale only | -| `resize: '100x100#'` | Exact dimensions | May crop | -| `resize: '100x100^'` | Minimum dimensions | May crop | - ---- - -## 16. Best Practices - -### Code Organization - -``` -app/ -├── views/ -│ ├── pages/ # Route handlers -│ ├── layouts/ # Page wrappers -│ └── partials/ -│ ├── components/ # UI components -│ ├── forms/ # Form partials -│ └── helpers/ # Utility partials -├── forms/ # Form configurations -├── graphql/ # Data queries -│ ├── records/ -│ ├── users/ -│ └── system/ -└── schema/ # Table definitions -``` - -### Naming Conventions - -| Component | Convention | Example | -|-----------|------------|---------| -| Tables | snake_case | `blog_post` | -| Properties | snake_case | `published_at` | -| Pages | snake_case | `about_us.liquid` | -| Partials | snake_case | `header.liquid` | -| Forms | snake_case | `contact_form.liquid` | -| GraphQL | snake_case | `get_blog_posts.graphql` | - -### Security Best Practices - -1. **Always use authorization policies** for protected routes -2. **Validate all inputs** using form validations -3. **Escape output** using Liquid's auto-escaping -4. **Use HTTPS** for all production instances -5. **Store secrets** in Partner Portal constants, not code -6. **Sanitize user content** before displaying - -### Performance Best Practices - -1. **Use pagination** for all list queries -2. **Load related records** in single GraphQL query -3. **Use background jobs** for long operations -4. **Cache expensive queries** using static cache -5. **Optimize images** before uploading as assets -6. **Minimize GraphQL response size** with specific field selection - -### Error Handling - -```liquid -{% graphql result = 'create_record', name: name %} - -{% if result.record_create.errors %} -
- {% for error in result.record_create.errors %} -

{{ error.message }}

- {% endfor %} -
-{% else %} -

Success! ID: {{ result.record_create.id }}

-{% endif %} -``` - ---- - -## 17. Common Gotchas & Pitfalls - -### 1. Variable Scope in Background Jobs - -**WRONG:** -```liquid -{% assign user_id = context.current_user.id %} -{% background %} - {{ user_id }} {# nil - not passed #} -{% endbackground %} -``` - -**CORRECT:** -```liquid -{% assign user_id = context.current_user.id %} -{% background user_id: user_id %} - {{ user_id }} {# Works! #} -{% endbackground %} -``` - -### 2. N+1 Query Problem - -**WRONG (N+1 queries):** -```liquid -{% graphql companies = 'get_companies' %} -{% for company in companies.records.results %} - {% graphql programmers = 'get_programmers', company_id: company.id %} - {# Each iteration = 1 query! #} -{% endfor %} -``` - -**CORRECT (single query):** -```graphql -query get_companies_with_programmers { - records( - filter: { table: { value: "company" } } - ) { - results { - id - properties - programmers: related_records( - table: "programmer" - foreign_property: "company_id" - ) { - id - properties - } - } - } -} -``` - -### 3. Form Field Name Format - -**WRONG:** -```liquid - {# Won't bind to form #} -``` - -**CORRECT:** -```liquid - -``` - -### 4. Module File References - -**WRONG:** -```liquid -{% render 'modules/my_module/public/header' %} -``` - -**CORRECT:** -```liquid -{% render 'modules/my_module/header' %} -``` - -### 5. Date/Time Formatting - -**WRONG:** -```liquid -{{ '2024-01-01' | strftime: '%Y' }} {# Error - not a time object #} -``` - -**CORRECT:** -```liquid -{{ '2024-01-01' | to_time | strftime: '%Y' }} -``` - -### 6. Array vs JSONB Confusion - -**Arrays** - for simple lists: -```yaml -type: array -# Value: ["a", "b", "c"] -``` - -**JSONB** - for complex objects: -```yaml -type: jsonb -# Value: {"nested": {"key": "value"}} -``` - -### 7. Form Resource Owner - -**For public forms** (contact, newsletter): -```yaml -resource_owner: anyone -``` - -**For authenticated forms** (profile edit): -```yaml -resource_owner: self -``` - -**For admin forms**: -```yaml -resource_owner: anyone_with_token -authorization_policies: - - admin_only_policy -``` - -### 8. Whitespace in Liquid - -**Problem:** Extra whitespace in output -```liquid -{% if true %} - Content -{% endif %} -{# Outputs newlines around content #} -``` - -**Solution:** Use whitespace control -```liquid -{%- if true -%} - Content -{%- endif -%} -``` - -### 9. GraphQL Variable Types - -**Integer vs Float:** -```graphql -# Integer property -{ name: "count", value_int: 5 } - -# Float property -{ name: "price", value_float: 19.99 } -``` - -**Boolean:** -```graphql -{ name: "active", value_boolean: true } -``` - -### 10. Soft Delete vs Hard Delete - -**Soft delete** (default): -```graphql -mutation { - record_delete(id: "123") { - id - deleted_at # Timestamp set - } -} -``` - -**Hard delete** (permanent): -```graphql -mutation { - record_delete(id: "123", hard_delete: true) { - id - } -} -``` - -### 11. Reserved Names - -Avoid these reserved names for custom tables and properties: - -**System Fields (automatically created):** -- `id` - Record UUID -- `created_at` - Creation timestamp -- `updated_at` - Last update timestamp -- `deleted_at` - Soft delete timestamp -- `type_name` - Table name -- `properties` - Property container - -**Reserved Words:** -- `user`, `users` - Built-in User table -- `session`, `sessions` - Session management -- `record`, `records` - Record operations -- `constant`, `constants` - System constants -- `table`, `tables` - Table metadata - -### 12. Form Resource Owner Confusion - -| Value | When to Use | -|-------|-------------| -| `anyone` | Public forms (contact, newsletter) | -| `self` | User editing their own data | -| `anyone_with_token` | API endpoints with token auth | - -**Wrong:** -```yaml -resource_owner: self # Won't work for public contact form -``` - -**Correct:** -```yaml -resource_owner: anyone # For public forms -``` - -### 13. Module File Deletion Behavior - -By default, module files are **NOT deleted** during deploy to protect private files. - -To enable deletion for a module: -```yaml -# app/config.yml -modules_that_allow_delete_on_deploy: - - my_module -``` - -### 14. GraphQL Query Caching - -GraphQL queries are cached by default. To bypass cache: -```graphql -query { - records( - per_page: 10 - filter: { table: { value: "product" } } - ) @skip_cache { - results { id } - } -} -``` - -### 15. File Upload Size Limits - -| Upload Type | Max Size | -|-------------|----------| -| Direct S3 (single part) | 5 GB | -| Direct S3 (multipart) | 5 TB | -| Application-processed | 2 GB | - -### 16. Background Job Payload Limits - -```liquid -{# WRONG - payload too large #} -{% background data: huge_array_with_thousands_of_items %} - -{# CORRECT - pass reference only #} -{% background record_id: record_id %} - {% graphql record = 'get_record', id: record_id %} - {# Process data in background #} -{% endbackground %} -``` - -### 17. Liquid Truthiness - -In Liquid, only `nil` and `false` are falsy. Empty strings and zero are truthy: - -```liquid -{% if '' %}TRUE{% endif %} {# TRUE! #} -{% if 0 %}TRUE{% endif %} {# TRUE! #} -{% if empty_array %}TRUE{% endif %} {# FALSE (nil) #} -{% if false %}TRUE{% endif %} {# FALSE #} -``` - -Use `blank` and `present` for better checks: -```liquid -{% if '' == blank %}EMPTY{% endif %} {# EMPTY #} -{% if 0 == blank %}ZERO IS BLANK{% endif %} {# Not blank! #} -``` - ---- - -## 18. Performance Optimization - -### Measuring Performance - -**time_diff filter:** -```liquid -{% assign start = 'now' | to_time %} - -{% graphql posts = 'get_posts' %} - -{% assign duration = start | time_diff: 'now' %} -

Query took: {{ duration }}ms

-``` - -### Query Optimization - -**1. Select only needed fields:** -```graphql -# BAD - fetches everything -query { - records { results { properties } } -} - -# GOOD - specific fields -query { - records { - results { - id - properties - } - } -} -``` - -**2. Use pagination:** -```graphql -query { - records(per_page: 20, page: 1) { - total_entries - results { id } - } -} -``` - -**3. Load related records efficiently:** -```graphql -query { - records(filter: { table: { value: "order" } }) { - results { - id - items: related_records(table: "order_item") { - id - properties - } - } - } -} -``` - -### Caching Strategies - -**Static Cache (Edge Caching):** -```liquid ---- -slug: public-page -response_headers: - Cache-Control: public, max-age=3600 ---- -``` - -**Fragment Caching:** -```liquid -{% cache key: 'sidebar', expire: 3600 %} - {% graphql categories = 'get_categories' %} - {% for category in categories.records.results %} - {{ category.properties.name }} - {% endfor %} -{% endcache %} -``` - -### Background Job Optimization - -**Keep payloads small:** -```liquid -{# BAD - large payload #} -{% background data: huge_array %} - -{# GOOD - pass reference #} -{% assign job_id = 'process_' | append: record_id %} -{% background job_id: job_id, record_id: record_id %} - {% graphql record = 'get_record', id: record_id %} - {# Process in background #} -{% endbackground %} -``` - ---- - -## 19. Testing & CI/CD - -### pos-cli GUI - -```bash -# Start GUI for GraphQL development -pos-cli gui serve staging - -# Access at http://localhost:3333 -``` - -### platformOS Check - -```bash -# Install -npm install -g @platformos/platformos-check - -# Run checks -platformos-check - -# Auto-fix issues -platformos-check --auto-correct -``` - -### GitHub Actions CI - -**File:** `.github/workflows/platformos.yml` -```yaml -name: platformOS CI - -on: - push: - branches: [main] - pull_request: - branches: [main] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '18' - - - name: Install pos-cli - run: npm install -g @platformos/pos-cli - - - name: Deploy to Staging - run: pos-cli deploy staging - env: - MPKIT_TOKEN: ${{ secrets.MPKIT_TOKEN }} - MPKIT_URL: ${{ secrets.STAGING_URL }} - - - name: Run Tests - run: npm test -``` - -### Release Pool Setup - -1. Create dedicated test instances in Partner Portal -2. Configure GitHub secrets: - - `MPKIT_TOKEN` - - `STAGING_URL` - - `PRODUCTION_URL` - -### Testing Best Practices - -1. **Unit test** GraphQL queries -2. **Integration test** form submissions -3. **E2E test** critical user flows -4. **Performance test** with realistic data volumes -5. **Security test** authorization policies - ---- - -## 20. System Limitations - -### Resource Limits - -| Resource | Limit | Notes | -|----------|-------|-------| -| File upload size | 2GB | Assets and uploads | -| Background job payload | 100KB | Keep payloads small | -| Background job execution | 1-60 min | Depends on priority | -| GraphQL query complexity | Varies | Monitor performance | -| Records per query | Unlimited | Use pagination | -| Assets | Thousands | Use uploads for dynamic content | -| Uploads | Millions | No practical limit | - -### Background Job Limits - -| Priority | Max Execution | Use For | -|----------|---------------|---------| -| `high` | 1 minute | Critical, urgent tasks | -| `default` | 5 minutes | Standard operations | -| `low` | 60 minutes | Heavy processing | - -### Rate Limiting - -- API calls may be rate-limited based on plan -- Background job scheduling has queue limits -- GraphQL queries have complexity scoring - -### Reserved Names - -Avoid these names for custom tables/properties: -- `id`, `created_at`, `updated_at`, `deleted_at` -- `type_name`, `properties`, `user` -- Built-in Liquid objects and filters - ---- - -## 22. Data Import/Export - -### Exporting Data - -```bash -# Export all data from an instance -pos-cli data export staging --path=./export.json - -# Export specific tables -pos-cli data export staging --tables=products,orders --path=./products.json -``` - -### Importing Data - -```bash -# Import data to an instance -pos-cli data import staging ./export.json - -# Import with transformations -pos-cli data import staging ./data.json --transform=./transform.js -``` - -### Data Export Format - -```json -{ - "users": [ - { - "id": "123", - "email": "user@example.com", - "created_at": "2024-01-15T10:00:00Z", - "properties": { - "first_name": "John", - "last_name": "Doe" - } - } - ], - "records": { - "product": [ - { - "id": "456", - "properties": { - "name": "Widget", - "price": 19.99 - } - } - ] - } -} -``` - -### Programmatic Import with Migrations - -```liquid -{# app/migrations/20240115000000_import_products.liquid #} -{% parse_json data %} - {{ 'data/products.json' | load_file }} -{% endparse_json %} - -{% for product in data.products %} - {% graphql result = 'create_product', - name: product.name, - price: product.price, - sku: product.sku - %} - {% log result %} -{% endfor %} -``` - -### Cleaning Instance Data - -```bash -# WARNING: This deletes all data! -pos-cli data clean staging - -# Clean specific tables -pos-cli data clean staging --tables=products,orders -``` - ---- - -## 23. Quick Reference - -### File Templates - -**New Page:** -```liquid ---- -slug: my-page -layout: application ---- - -

Page Title

-``` - -**New Table:** -```yaml -name: my_table -properties: - - name: name - type: string -``` - -**New Form:** -```liquid ---- -name: my_form -resource: my_table -resource_owner: anyone -redirect_to: /success -fields: - properties: - name: - validation: - presence: true ---- - -{% form %} - - -{% endform %} -``` - -**New GraphQL Query:** -```graphql -query my_query($param: String) { - records(filter: { table: { value: "my_table" } }) { - results { id properties } - } -} -``` - -### Common Liquid Patterns - -**Conditional rendering:** -```liquid -{% if condition %} - -{% elsif other_condition %} - -{% else %} - -{% endif %} -``` - -**Loop with index:** -```liquid -{% for item in items %} - {{ forloop.index }}: {{ item.name }} -{% endfor %} -``` - -**Pagination:** -```liquid -{% if records.has_previous_page %} - Previous -{% endif %} - -{% if records.has_next_page %} - Next -{% endif %} -``` - -### Common GraphQL Patterns - -**Create with error handling:** -```graphql -mutation { - record_create(record: { table: "post", properties: [] }) { - id - errors { message } - } -} -``` - -**Update specific fields:** -```graphql -mutation { - record_update(id: "123", record: { properties: [{ name: "status", value: "published" }] }) { - id - properties - } -} -``` - -**Search with filters:** -```graphql -query { - records( - filter: { - table: { value: "product" } - properties: [{ name: "category", value: "electronics" }] - created_at: { gte: "2024-01-01" } + completed_at + failed_at + error_message } - ) { - results { id } } } ``` -### pos-cli Commands +### Payload Limits -```bash -# Authentication -pos-cli auth login # Login to Partner Portal - -# Development -pos-cli sync staging # Watch and sync changes -pos-cli deploy staging # Deploy to instance -pos-cli deploy staging -f # Force deploy (delete missing files) +Keep background job payloads under 100KB. For large data, pass references (IDs) and fetch data inside the job: -# Data -pos-cli data export staging # Export instance data -pos-cli data import staging file.json # Import data -pos-cli migrations run staging # Run pending migrations +```liquid +{% background record_id: record_id, source_name: 'process' %} + {% graphql record = 'records/find', id: record_id %} + {# Process the record #} +{% endbackground %} +``` -# Modules -pos-cli modules install module_name # Install module -pos-cli modules remove module_name # Remove module +--- -# GUI -pos-cli gui serve staging # Start development GUI +## 21. Migrations -# Logs -pos-cli logs staging # Stream logs -``` - -### Error Messages Reference - -| Error | Cause | Solution | -|-------|-------|----------| -| `Record not found` | Invalid ID | Check record exists | -| `Validation failed` | Invalid data | Check form validations | -| `Unauthorized` | Policy failed | Check authorization | -| `Rate limited` | Too many requests | Add delays, use caching | -| `Timeout` | Query too slow | Optimize query, add pagination | -| `Property not found` | Wrong property name | Check table schema | -| `Table not found` | Wrong table name | Check table definition | -| `Form not found` | Wrong form name | Check form file exists | - -### GraphQL Property Type Mapping - -| Property Type | GraphQL Input | Example | -|---------------|---------------|---------| -| `string` | `value: "text"` | `{ name: "title", value: "Hello" }` | -| `integer` | `value_int: 42` | `{ name: "count", value_int: 5 }` | -| `float` | `value_float: 19.99` | `{ name: "price", value_float: 19.99 }` | -| `boolean` | `value_boolean: true` | `{ name: "active", value_boolean: true }` | -| `date` | `value: "2024-01-15"` | `{ name: "birthday", value: "2024-01-15" }` | -| `datetime` | `value: "2024-01-15T10:00:00Z"` | ISO 8601 format | -| `array` | `value_array: ["a", "b"]` | `{ name: "tags", value_array: ["a", "b"] }` | -| `jsonb` | `value_json: "{}"` | JSON string | -| `upload` | Via form only | File uploads | - -### Form Validation Reference - -| Validation | Syntax | Description | -|------------|--------|-------------| -| `presence` | `presence: true` | Required field | -| `email` | `email: true` | Valid email format | -| `uniqueness` | `uniqueness: true` | Must be unique | -| `length` | `length: { minimum: 5, maximum: 100 }` | String length | -| `numericality` | `numericality: { greater_than: 0 }` | Number range | -| `confirmation` | `confirmation: true` | Must match confirmation field | -| `url` | `url: true` | Valid URL format | - -### pos-cli Extended Commands +Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications. -```bash -# Authentication -pos-cli auth login # Login to Partner Portal -pos-cli auth logout # Logout - -# Development -pos-cli sync staging # Watch and sync changes -pos-cli sync staging --live-reload # With live reload -pos-cli deploy staging # Deploy to instance -pos-cli deploy staging -f # Force deploy (delete missing files) -pos-cli deploy staging --direct-assets # Deploy assets directly - -# Data Management -pos-cli data export staging # Export all data -pos-cli data export staging --tables=products,orders -pos-cli data import staging file.json # Import data -pos-cli data clean staging # Delete all data (DANGER!) -pos-cli migrations run staging # Run pending migrations -pos-cli migrations status staging # Check migration status +### File Structure -# Modules -pos-cli modules install module_name # Install module -pos-cli modules install module_name@1.2 # Specific version -pos-cli modules remove module_name # Remove module -pos-cli modules list staging # List installed modules +``` +app/migrations/ +├── 20240115120000_seed_initial_data.liquid +├── 20240116093000_add_default_categories.liquid +└── 20240120150000_init_staging_constants.liquid +``` -# GUI Tools -pos-cli gui serve staging # Start development GUI -pos-cli gui serve staging --port 3333 # Custom port +Files MUST be named with UTC timestamp prefix for chronological execution. -# Logs -pos-cli logs staging # Stream logs -pos-cli logs staging --tail 100 # Last 100 lines -pos-cli logs staging --follow # Follow new logs +### Creating a Migration -# Environment -pos-cli env list # List environments -pos-cli env add production # Add environment -pos-cli env remove staging # Remove environment +```bash +pos-cli migrations generate dev init_staging_constants +# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid +``` -# Testing -pos-cli test staging # Run tests +### Example: Initialize Staging Constants -# Debug -pos-cli shell staging # Interactive shell +```liquid +{% liquid + if context.environment == 'staging' + graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123' + graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com' + endif +%} ``` ---- +### Example: Seed Data -## 24. Translations +```liquid +{% parse_json categories %} +["Electronics", "Clothing", "Books"] +{% endparse_json %} -### Overview +{% for category in categories %} + {% graphql _ = 'categories/create', name: category %} +{% endfor %} +``` -Translations serve three main purposes: -1. **Multi-language sites** - Static copy in multiple languages -2. **Date formatting** - Consistent date/time display -3. **Flash messages** - System message localization +### Running Migrations -### Translation Files +- **Automatic:** Pending migrations run on `pos-cli deploy` +- **Manual:** `pos-cli migrations run TIMESTAMP dev` -**File:** `app/translations/en.yml` -```yaml -en: - hello: "Hello" - welcome: "Welcome to our site" - buttons: - submit: "Submit" - cancel: "Cancel" - errors: - not_found: "Page not found" -``` +### Migration States -**File:** `app/translations/es.yml` -```yaml -es: - hello: "Hola" - welcome: "Bienvenido a nuestro sitio" - buttons: - submit: "Enviar" - cancel: "Cancelar" - errors: - not_found: "Página no encontrada" -``` +- **pending** — not yet executed (runs on next deploy) +- **done** — successfully completed (will not run again) +- **error** — failed (can edit and retry) -### Using Translations in Liquid +### Migration Best Practices -**Basic translation:** +1. **Make migrations idempotent** — running twice should not cause errors: ```liquid -{{ 'hello' | t }} # Output: Hello (or Hola) +{% graphql record = 'records/find', id: record_id %} +{% unless record.properties.status %} + {% graphql _ = 'records/update', id: record_id, status: 'active' %} +{% endunless %} ``` -**Nested keys:** +2. **Use background jobs for large migrations:** ```liquid -{{ 'buttons.submit' | t }} # Output: Submit -{{ 'errors.not_found' | t }} # Output: Page not found +{% background source_name: 'data_migration', priority: 'low' %} + {% graphql records = 'records/list_all' %} + {% for record in records.records.results %} + {# Process each record #} + {% endfor %} +{% endbackground %} ``` -**With interpolation:** -```yaml -# en.yml -welcome_user: "Welcome, {{ name }}!" -``` +3. **Test migrations on staging first** +4. **Log progress:** ```liquid -{{ 'welcome_user' | t: name: user.first_name }} +{% log 'Migration started' %} +{% log 'Processed 50 records' %} ``` -### Date Localization +For large data imports, use Data Import/Export instead of migrations. -Use the `l` (localize) filter for consistent date formatting: +--- -```yaml -# en.yml -date: - formats: - short: "%b %d, %Y" - long: "%B %d, %Y %H:%M" -``` -```liquid -{{ 'now' | l: 'short' }} # Jan 15, 2024 -{{ post.published_at | l: 'long' }} # January 15, 2024 14:30 -``` +## 22. Data Import/Export -### Language Detection +### Exporting Data -platformOS automatically detects language from: -1. User's `language` property (if set) -2. Browser's Accept-Language header -3. Default language (English) +```bash +# Export all data +pos-cli data export staging --path=./export.json -Access current language: -```liquid -{{ context.language }} # Current language code (e.g., "en") +# Export specific tables +pos-cli data export staging --tables=products,orders --path=./products.json ``` ---- - -## 25. Activity Feeds - -### Overview +### Importing Data -Activity Feeds implement the [W3C Activity Streams 2.0](https://www.w3.org/TR/2017/REC-activitystreams-core-20170523/) specification for tracking user activities. +```bash +# Import data +pos-cli data import staging ./export.json -**Key Characteristics:** -- Activities are **immutable** (append-only) -- Each activity has a **unique UUID** -- Activities can be shared between actors -- Activities represent events that happened in the past +# Import with transformations +pos-cli data import staging ./data.json --transform=./transform.js +``` -### Activity Structure +### Export Format ```json { - "actor": { - "type": "Person", - "id": "User.1", - "name": "Sally Smith" - }, - "type": "Create", - "object": { - "type": "Relationship", - "id": "Relationship.42" - }, - "target": { - "type": "Group", - "id": "Group.5" - } -} -``` - -### Creating Activities - -**GraphQL Mutation:** -```graphql -mutation create_activity { - activity_create( - activity: { - type: "Join" - actor: { - type: "Person" - id: "User.123" - name: "John Doe" - } - object: { - type: "Group" - id: "Group.456" - } + "users": [ + { + "id": "123", + "email": "user@example.com", + "properties": { "first_name": "John" } } - ) { - id - uuid + ], + "records": { + "product": [ + { + "id": "456", + "properties": { "name": "Widget", "price": 19.99 } + } + ] } } ``` -### Publishing to Feeds - -After creating an activity, publish it to feeds: - -```graphql -mutation publish_to_feed { - feed_publish( - feed_id: "user_123_notifications" - activity_uuid: "abc-123-uuid" - ) { - id - } -} -``` +### Cleaning Instance Data -### Querying Feeds +```bash +# WARNING: Deletes all data! +pos-cli data clean staging -```graphql -query get_user_feed { - feeds( - feed_id: "user_123_notifications" - per_page: 20 - ) { - total_entries - results { - id - uuid - type - actor - object - target - created_at - } - } -} +# Clean specific tables +pos-cli data clean staging --tables=products,orders ``` -### Common Activity Types - -| Type | Description | -|------|-------------| -| `Create` | Created something | -| `Update` | Updated something | -| `Delete` | Deleted something | -| `Join` | Joined a group/event | -| `Leave` | Left a group/event | -| `Follow` | Started following | -| `Like` | Liked content | -| `Comment` | Commented on content | -| `Share` | Shared content | -| `Approve` | Approved a request | - --- -## 26. JSON Documents - -### Overview +## 23. JSON Documents -JSON Documents provide a schemaless data storage option for flexible, document-based data. Unlike Records (which require a Table schema), JSON Documents can store any valid JSON structure. +JSON Documents provide schemaless data storage for flexible, document-based data. -**Use Cases:** -- Configuration data -- Unstructured content -- Temporary data storage -- Data that doesn't fit a rigid schema +**Use Cases:** Configuration data, unstructured content, temporary data storage. ### Creating JSON Documents -**GraphQL Mutation:** ```graphql -mutation create_json_document { +mutation { json_document_create( document: { name: "site_config" @@ -2895,51 +1360,36 @@ mutation create_json_document { id name content - created_at } } ``` -### Querying JSON Documents +### Querying ```graphql -query get_json_document { +query { json_document(name: "site_config") { id name content - created_at - updated_at } -} -query list_json_documents { - json_documents( - per_page: 10 - sort: [{ created_at: { order: DESC } }] - ) { - results { - id - name - content - } + json_documents(per_page: 10) { + results { id name content } } } ``` -### Updating JSON Documents +### Updating ```graphql -mutation update_json_document { +mutation { json_document_update( name: "site_config" - document: { - content: "{\"theme\": \"light\", \"features\": [\"blog\", \"shop\", \"forum\"]}" - } + document: { content: "{\"theme\": \"light\"}" } ) { id content - updated_at } } ``` @@ -2947,46 +1397,85 @@ mutation update_json_document { ### Using in Liquid ```liquid -{% graphql config = 'get_json_document', name: 'site_config' %} +{% graphql config = 'json_documents/find', name: 'site_config' %} {% assign settings = config.json_document.content | parse_json %} - Theme: {{ settings.theme }} -Features: {{ settings.features | join: ', ' }} ``` -### JSON Document vs Records +--- -| Feature | JSON Documents | Records | -|---------|---------------|---------| -| Schema | Schemaless | Defined in Table YAML | -| Validation | None | Form validation | -| Structure | Any JSON | Fixed properties | -| Use Case | Config, flexible data | Structured entities | -| GraphQL | `json_document_*` | `record_*` | +## 24. Activity Feeds ---- +Activity Feeds implement the W3C Activity Streams 2.0 specification for tracking user activities. + +**Characteristics:** Activities are immutable (append-only), each has a unique UUID. + +### Creating Activities + +```graphql +mutation { + activity_create( + activity: { + type: "Join" + actor: { type: "Person", id: "User.123", name: "John" } + object: { type: "Group", id: "Group.456" } + } + ) { + id + uuid + } +} +``` + +### Publishing to Feeds + +```graphql +mutation { + feed_publish( + feed_id: "user_123_notifications" + activity_uuid: "abc-123-uuid" + ) { id } +} +``` + +### Querying Feeds -## 27. AI Embeddings +```graphql +query { + feeds(feed_id: "user_123_notifications", per_page: 20) { + total_entries + results { id uuid type actor object target created_at } + } +} +``` + +### Common Activity Types + +| Type | Description | +|------|-------------| +| `Create` | Created something | +| `Update` | Updated something | +| `Delete` | Deleted something | +| `Join` | Joined a group | +| `Follow` | Started following | +| `Like` | Liked content | +| `Comment` | Commented | +| `Approve` | Approved a request | -### Overview +--- -platformOS supports AI embeddings for semantic search and similarity matching. Embeddings are vector representations of text that capture semantic meaning. +## 25. AI Embeddings -**Use Cases:** -- Semantic search -- Content recommendation -- Similarity matching -- Clustering +platformOS supports AI embeddings for semantic search and similarity matching. ### Creating Embeddings -**GraphQL Mutation:** ```graphql -mutation create_embedding { +mutation { embedding_create( embedding: { name: "product_description" - value: "High-quality wireless headphones with noise cancellation" + value: "High-quality wireless headphones" target_id: "product_123" target_type: "Product" } @@ -3000,7 +1489,7 @@ mutation create_embedding { ### Semantic Search ```graphql -query semantic_search { +query { embeddings_search( query: "wireless audio devices" limit: 10 @@ -3009,7 +1498,6 @@ query semantic_search { results { id target_id - target_type similarity value } @@ -3017,138 +1505,132 @@ query semantic_search { } ``` -### Querying Embeddings +### Parameters -```graphql -query get_embedding { - embedding( - target_id: "product_123" - target_type: "Product" - ) { - id - name - value - vector - created_at - } -} -``` +| Parameter | Description | +|-----------|-------------| +| `name` | Embedding type identifier | +| `value` | Text to embed | +| `target_id` | Associated entity ID | +| `target_type` | Associated entity type | -### Deleting Embeddings +--- -```graphql -mutation delete_embedding { - embedding_delete( - target_id: "product_123" - target_type: "Product" - ) { - id - } -} -``` +## 26. Testing -### Embedding Parameters +Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. -| Parameter | Description | -|-----------|-------------| -| `name` | Identifier for the embedding type | -| `value` | The text to embed | -| `target_id` | ID of the associated entity | -| `target_type` | Type of the associated entity | -| `vector` | The computed embedding vector (read-only) | +Every new feature MUST have unit tests for commands. + +```liquid +{% function result = 'commands/products/create', title: "Test" %} +{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %} +{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %} +{% return contract %} +``` + +Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. --- -## 28. Migrations +## 27. CLI Commands -### Overview +```bash +# Deployment +pos-cli deploy dev -Migrations are Liquid scripts that run once to transform data. They are useful for: -- Data transformations during schema changes -- Bulk data updates -- One-time data imports +# Sync (MUST sync every file after modification) +pos-cli sync dev -### Creating Migrations +# Logs +pos-cli logs dev -**File:** `app/migrations/20240115120000_add_status_to_products.liquid` -```liquid -{% graphql products = 'get_all_products' %} +# Linting (MUST run after EVERY file change) +platformos-check -{% for product in products.records.results %} - {% graphql result = 'update_product_status', - id: product.id, - status: 'active' - %} - {% log result %} -{% endfor %} -``` +# Run Liquid inline +pos-cli exec liquid dev '' -### Migration File Naming +# Run GraphQL inline +pos-cli exec graphql dev '' -Migrations are executed in alphabetical order. Use timestamps as prefixes: -``` -app/migrations/ -├── 20240101000000_initial_setup.liquid -├── 20240115120000_add_status.liquid -└── 20240201000000_migrate_images.liquid -``` +# Tests +pos-cli test run staging -### Running Migrations +# Modules +pos-cli modules install +pos-cli modules download -```bash -# Run pending migrations -pos-cli migrations run staging +# Constants +pos-cli constants set --name KEY --value "value" dev -# Check migration status -pos-cli migrations status staging -``` +# Generate CRUD +pos-cli generate run modules/core/generators/crud --include-views -### Migration Best Practices +# Migrations +pos-cli migrations generate dev +pos-cli migrations run TIMESTAMP dev -1. **Make migrations idempotent** - Running twice should not cause errors: -```liquid -{% graphql product = 'get_product', id: product_id %} -{% unless product.record.properties.status %} - {# Only update if status is not set #} - {% graphql result = 'update_product', id: product_id, status: 'active' %} -{% endunless %} +# Data Import/Export +pos-cli data export staging --path=./export.json +pos-cli data import staging ./data.json +pos-cli data clean staging ``` -2. **Use background jobs for large migrations:** -```liquid -{% background source_name: 'data_migration' %} - {% graphql records = 'get_all_records' %} - {% for record in records.records.results %} - {# Process each record #} - {% endfor %} -{% endbackground %} -``` +--- -3. **Test migrations on staging first** -4. **Log progress for debugging:** -```liquid -{% log 'Migration started' %} -{% log 'Processed ' | append: count | append: ' records' %} -``` +## 28. Modules Reference -### Migration Limitations +| Module | Install | Purpose | Required | +|--------|---------|---------|----------| +| `core` | Required | Commands, events, validators | YES | +| `user` | Required | Auth, RBAC, OAuth2 | YES | +| `common-styling` | Required | CSS, components | YES | +| `tests` | Optional | Testing framework | YES (for testing) | +| `payments` + `payments_stripe` | Optional | Stripe payments | No | +| `chat` | Optional | WebSocket messaging | No | +| `openai` | Optional | OpenAI integration | No | + +--- -- Migrations run as background jobs -- Should complete within a few minutes -- For long-running operations, use low-priority background jobs -- Failed migrations can be retried +## 29. Forbidden Behaviors + +You MUST NOT: +- Edit files in `./modules/` (read-only) +- Break long lines in `{% liquid %}` blocks (causes syntax errors) +- Invent Liquid tags, filters, or GraphQL types that do not exist +- Bypass security (CSRF tokens, authorization) +- Access databases directly outside GraphQL +- Deploy without running `platformos-check` +- Sync files outside `./app/` +- Hardcode API keys, secrets, or environment-specific URLs +- Hardcode user-facing text in partials (use translations) +- Put HTML, JS, or CSS in page files +- Call GraphQL from partials +- Put raw GraphQL in pages (use `.graphql` files) +- Create or modify application files outside the `app/` directory +- Use reserved names (`id`, `created_at`, `deleted_at`, `type_name`, `properties`) as custom property/table names --- -## Resources +## 30. Pre-Flight Checklist -- **Documentation:** https://documentation.platformos.com/ -- **API Reference:** https://documentation.platformos.com/api-reference -- **Examples:** https://examples.platform-os.com/ -- **GitHub:** https://github.com/Platform-OS -- **Partner Portal:** https://partners.platformos.com/ -- **Community:** https://community.platformos.com/ +Before every change, verify: ---- +- [ ] No underscore prefix in partial filenames +- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid` +- [ ] Pages have ONE HTTP method each +- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files) +- [ ] No HTML/JS/CSS in pages +- [ ] No hardcoded text in partials (use translations) +- [ ] `platformos-check` passes with 0 errors +- [ ] Every file synced after modification +- [ ] All list queries support pagination (`per_page`, `page`) +- [ ] All inputs validated in commands before persisting +- [ ] CSS/JS minified, `asset_url` used for cache busting + +### Asset URL Usage -*This guide is designed for LLM agents developing on platformOS. For the most up-to-date information, always refer to the official documentation.* +```liquid +{{ 'images/img.png' | asset_url }} +``` diff --git a/src/data/resources/platformos-development-guide.md~ b/src/data/resources/platformos-development-guide.md~ new file mode 100644 index 0000000..40929c1 --- /dev/null +++ b/src/data/resources/platformos-development-guide.md~ @@ -0,0 +1,1636 @@ +# platformOS Development Guide + +Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory +workflow — read it before touching any file. + +## 0. MANDATORY WORKFLOW — Read Before Writing Any Code + +**You are STRICTLY FORBIDDEN from skipping this workflow** + +You MUST follow this loop for every feature. Each step produces structured output +the next step consumes — skipping any step produces invalid state that downstream +tools will reject. + +1. **`project_map`** — understand what already exists. MUST be called once per session + before any scaffold or write. +2. **`scaffold(type, name, properties, write: false)`** — generate the authoritative + file set from platformOS-native templates. MUST use scaffold whenever a file set + matches one of its types (crud, api, command, query, partial, page). +3. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files. + Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains + rules that are NOT in your training data and that differ from Shopify, Rails, and + generic Liquid. +4. **`validate_intent` — declare your plan before touching disk.** + Two modes, pick by what you're doing next: + + - **Mode A — hand-drafted batch (REQUIRED before manual writes).** + Call `validate_intent({ intent: { goal, changes: [...] } })` where + `changes` is an array of `{ path, role, action, references? }` — one + entry per file you intend to author. The plan is the contract for the + rest of the session. + - **Mode B — scaffold review (OPTIONAL).** + Call `validate_intent({ scaffold_output: })` + only if you want a second look at the generated set before committing. + The default scaffold path skips this step. + + **Read the response:** + - `ok: false` → fix `errors[].suggestion`, re-call. MUST NOT proceed. + - `ok: true` + `write_directly: true` → Mode B; go straight to + `scaffold(..., write: true)`. + - `ok: true` + `write_directly: false` → Mode A; draft each file, call + `validate_code` on the full content, then write. + + **What `pending_files` / `pending_translations` / `pending_pages` are for:** + you can ignore them. The supervisor stores them and uses them to suppress + false-positive `MissingPartial` / `TranslationKeyExists` errors in later + `validate_code` / `analyze_project` calls — because those files are + *promised* by the plan but not on disk yet. You do not pass them to any + subsequent tool; the server merges them automatically. + + **Skipping Mode A before hand-drafted writes** is the #1 cause of phantom + cross-reference errors: `validate_code` will flag every partial and + translation key the plan hasn't written yet, and the agent chases those + ghosts by deleting the references the plan needs. + + **Scope drift:** if you add, rename, or drop a file that isn't in the + current `changes` array, re-call `validate_intent` with the updated plan + before writing the new file. + +5. **`scaffold(..., write: true)`** — writes all files to disk. If you went + through Mode B in step 4, this runs after `write_directly: true`. + Otherwise this is the direct follow-up to step 2. For hand-drafted edits + (Mode A, or manual edits without scaffold), call `validate_code` per file + and only write when validation passes — never rely on scaffold to write a + hand-authored file. +6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or + `must_fix_before_write: true`, fix every error and re-validate. MUST NOT + write the file to disk until validation passes. +7. Creation order matters: schema → graphql → partial → page. +8. **`analyze_project` — project-wide health check.** MUST be called: + - **Before reporting task completion.** `validate_code` only sees one + file at a time; cross-file damage (broken render targets, orphaned + partials, dangling translations, schema drift) only surfaces from the + whole-project view. A task is not done until `analyze_project` returns + zero new errors or warnings introduced by this session. + - **When you feel lost.** If validate_code keeps reporting errors you + don't understand, if the same check keeps re-appearing after you + "fixed" it, if you suspect a file you edited affected callers you + can't see, or if `project_map` no longer matches your mental model — + stop editing and call `analyze_project` to re-ground. It returns + per-file error counts, the dependency graph, orphaned files, broken + references, and schema issues for every file in `app/`. That is the + authoritative picture of the project right now. + + `analyze_project` respects `session.pending` — files declared in a + validated plan are not flagged as missing. You do not need to pass any + parameters for the standard case; omit `files` to analyze the whole + project. + + MUST NOT: skip this step before announcing "done" just because + `validate_code` passed on the files you edited. Individual-file green + lights do not imply project integrity. + +### MUST-CALL domains (by feature type) + +- **Auth code** — `domain_guide(domain: "authentication")` +- **Any form** — `domain_guide(domain: "forms")` +- **New pages** — `domain_guide(domain: "pages")` +- **New partials** — `domain_guide(domain: "partials")` +- **GraphQL ops** — `domain_guide(domain: "graphql")` +- **Any new domain** — `domain_guide(domain: "", section: "gotchas")` + +### MUST NOT + +- Use `{% include %}` for app code — deprecated. Use `{% render %}` or + `{% function %}`. +- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These + do not exist in platformOS. +- Write files to disk without calling `validate_code` on the proposed content first. +- Assume module call syntax from memory — call `module_info(name)` to get the + authoritative live-scan API surface. +- Ignore `consult_before_writing` in a scaffold response. Every domain listed there + MUST be consulted via `domain_guide` before step 5. + +### Session-start checklist + +Before your first tool call, the following are true: + +- [ ] `server_status` called — confirms LSP and indexes are ready, lists + `domain_guides` and `session_pending`. +- [ ] `load_development_guide` called (this document) — re-read if you lose + context or are unsure which step comes next. +- [ ] `project_map` called once for full project baseline. + +Proceed only when all three are checked. + +--- + +## 1. Technology Stack + +platformOS uses three primary technologies: +- **Liquid** — server-side templating language +- **GraphQL** — data operations (built-in queries/mutations only) +- **YAML** — configuration for schemas, translations, and settings + +The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access. + +platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag. + +### Source of Truth + +The official platformOS documentation is the ONLY source of truth: + +| Resource | URL | +|----------|-----| +| Official Docs | documentation.platformos.com | +| GraphQL Schema | documentation.platformos.com/api/graphql/schema | +| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md | +| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md | +| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md | +| Core Module | github.com/Platform-OS/pos-module-core (README) | +| User Module | github.com/Platform-OS/pos-module-user (README) | +| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) | +| Payments Module | github.com/Platform-OS/pos-module-payments (README) | +| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) | +| Tests Module | github.com/Platform-OS/pos-module-tests (README) | +| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md | + +You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation. + +--- + +## 2. Directory Structure + +``` +project-root/ +├── app/ +│ ├── assets/ # Static files (images, fonts, styles, scripts) +│ ├── views/ +│ │ ├── pages/ # Controllers — NO HTML here +│ │ ├── layouts/ # Wrapper templates +│ │ └── partials/ # Reusable template snippets +│ ├── lib/ +│ │ ├── commands/ # Business logic (build -> check -> execute) +│ │ ├── queries/ # Data retrieval wrappers +│ │ ├── events/ # Event definitions +│ │ └── consumers/ # Event handlers +│ ├── schema/ # Database table definitions (YAML) +│ ├── graphql/ # GraphQL query/mutation files +│ ├── forms/ # Form configurations (YAML + Liquid front matter) +│ ├── emails/ # Email templates +│ ├── smses/ # SMS templates +│ ├── api_calls/ # Third-party API integrations +│ ├── translations/ # i18n content (YAML) +│ ├── authorization_policies/ # Access control rules (page/form level) +│ ├── migrations/ # One-time migration scripts +│ └── config.yml # Feature flags +├── modules/ # Downloaded/custom modules (READ-ONLY) +│ └── MODULE_NAME/ +│ ├── public/ # Publicly accessible files +│ └── private/ # IP-protected files (not downloadable) +└── .pos # Environment endpoints +``` + +All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`. + +The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only. + +### Module Structure Details + +Modules have `public/` and `private/` subdirectories with the same internal structure: + +``` +modules/my_module/ +├── public/ +│ ├── views/ +│ ├── forms/ +│ ├── graphql/ +│ └── assets/ +└── private/ + ├── views/ + └── forms/ +``` + +- **Public files** — accessible for preview/download after deployment +- **Private files** — IP-protected, not accessible for download +- When referencing module files, omit `public/` and `private/` from the path +- Files with the same name in both directories will conflict — do not do this + +**Module file referencing:** +```liquid +{% render 'modules/my_module/header' %} +{% graphql result = 'modules/my_module/get_data' %} +{% render_form 'modules/my_module/contact_form' %} +{{ 'modules/my_module/style.css' | asset_url }} +``` + +**Module deletion behavior:** By default, module files are NOT deleted during `pos-cli deploy` to protect private files. To enable deletion: +```yaml +# app/config.yml +modules_that_allow_delete_on_deploy: + - my_module +``` + +### File Naming Conventions + +| Directory | Pattern | Example | +|-----------|---------|---------| +| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` | +| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` | +| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` | +| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` | +| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` | +| Assets | `app/assets//` | `app/assets/images/logo.png` | +| Translations | `app/translations/.yml` | `app/translations/en.yml` | + +### File Formats + +| Extension | Content-Type | URL | +|-----------|--------------|-----| +| `*.liquid` or `*.html.liquid` | `text/html` | `/path` | +| `*.json.liquid` | `application/json` | `/path.json` | +| `*.js.liquid` | `application/javascript` | `/path.js` | + +--- + +## 3. Architecture Rules + +### Pages MUST Be Controllers + +Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method. + +### Business Logic MUST Live in Commands + +All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build -> check -> execute pattern. + +### Path Resolution + +- `{% render 'blog_posts/card' %}` -> `app/views/partials/blog_posts/card.liquid` +- `{% function r = 'commands/blog_posts/create' %}` -> `app/lib/commands/blog_posts/create.liquid` +- `{% function r = 'queries/blog_posts/search' %}` -> `app/lib/queries/blog_posts/search.liquid` + +The `lib/` prefix is implicit in `function` calls — do NOT include it. + +### Separation of Concerns + +- UI (Liquid templates) MUST be in partials and layouts +- Data operations (GraphQL) MUST be in query/mutation files +- Logic (commands) MUST be in `app/lib/commands/` + +### Modules First + +Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic. + +### Generators First (DEPRECATED — DO NOT USE) + +You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available. + +--- + +## 4. Pages + +Pages are controllers — they handle routing, fetch data, and delegate to partials. + +### Front Matter + +```liquid +--- +slug: products/:id +method: post +layout: application +metadata: + title: "Product Details" +--- +``` + +**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** + +| Property | Default | Notes | +|----------|---------|-------| +| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | +| `method` | `get` | `get`, `post`, `put`, `delete` | +| `layout` | `application` | Empty string for no layout | + +### Dynamic Routes + +| Pattern | URL | `context.params` | +|---------|-----|------------------| +| `products/:id` | `/products/123` | `{ "id": "123" }` | +| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` | +| `search(/:q)` | `/search/books` | `{ "q": "books" }` | + +### REST CRUD Convention + +| HTTP Method | URL Slug | Page File | GraphQL | Purpose | +|-------------|----------|-----------|---------|---------| +| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form | +| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource | +| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource | +| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form | +| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource | +| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource | +| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources | + +### CSRF Protection + +Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous). + +### GET Page Example + +```liquid +--- +slug: articles/:id +method: get +--- +{% liquid + function article = 'queries/articles/find', id: context.params.id + + if article == blank + render '404' + break + endif + + render 'articles/show', article: article +%} +``` + +### POST Page Example + +```liquid +--- +slug: articles +method: post +--- +{% liquid + function result = 'commands/articles/create', object: context.params.article + + if result.valid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname + redirect_to '/articles' + else + render 'articles/new', result: result + endif +%} +``` + +--- + +## 5. Partials & Layouts + +### Partials + +Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`). + +Partials MUST NOT have underscore-prefixed filenames. + +The render path maps: `render 'path/name'` -> `app/views/partials/path/name.liquid`. + +### Layouts + +The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout. + +--- + +## 6. Commands (Business Logic) + +All business logic MUST be encapsulated in commands following the build -> check -> execute pattern. + +### Main Command + +```liquid +{% doc %} + @param object {object} - Article data +{% enddoc %} + +{% liquid + function object = 'commands/articles/create/build', object: object + function object = 'commands/articles/create/check', object: object + + if object.valid + function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object + endif + + return object +%} +``` + +### Build Stage + +Normalizes and structures input data: + +```liquid +{% doc %} + @param object {object} - form params +{% enddoc %} + +{% liquid + assign object['title'] = object.title + assign object['body'] = object.body + + return object +%} +``` + +### Check Stage + +Validates the built object: + +```liquid +{% doc %} + @param object {object} - form params +{% enddoc %} + +{% liquid + assign c = '{ "errors": {}, "valid": true }' | parse_json + + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title' + function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body' + + assign object = object | hash_merge: valid: c.valid, errors: c.errors + + return object +%} +``` + +### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE) + +> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`). + +```liquid +{% comment %} WRONG — these partials do not exist: {% endcomment %} +{% function object = 'modules/core/commands/build', object: object %} +{% function object = 'modules/core/commands/check', object: object, + validators: '[{"name": "presence", "property": "title"}]' +%} + +{% comment %} CORRECT — only execute is shared: {% endcomment %} +{% if object.valid %} + {% function object = 'modules/core/commands/execute', + mutation_name: 'products/create', selection: 'record', object: object + %} +{% endif %} + +{% return object %} +``` + +### Events + +```liquid +{% comment %} Publish an event {% endcomment %} +{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %} + +{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %} +{% graphql _ = 'emails/send_confirmation', email: event.object.email %} +``` + +All inputs MUST be validated in commands before persisting. + +--- + +## 7. GraphQL + +GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively. + +### Query Wrapper Pattern + +```liquid +{% doc %} + @param id {string} - Article ID +{% enddoc %} + +{% liquid + graphql result = 'articles/find', id: id + return result.records.results | first +%} +``` + +### Search with Pagination + +```graphql +query search($page: Int = 1, $keyword: String) { + records( + page: $page + per_page: 20 + filter: { + table: { value: "article" } + properties: [{ name: "title", contains: $keyword }] + } + sort: { created_at: { order: DESC } } + ) { + total_pages + results { + id + title: property(name: "title") + body: property(name: "body") + } + } +} +``` + +All list queries MUST support `per_page` and `page` arguments for pagination. + +### Find by ID + +```graphql +query find($id: ID!) { + records( + per_page: 1 + filter: { + id: { value: $id } + table: { value: "article" } + } + ) { + results { + id + title: property(name: "title") + } + } +} +``` + +### Related Records (Avoids N+1) + +```graphql +results { + id + # belongs-to (single) + author: related_record(table: "user", join_on_property: "user_id") { + email + } + # has-many + comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") { + body: property(name: "body") + } +} +``` + +### Upload Property + +```graphql +image: property_upload(name: "image") { url } +``` + +### Mutations + +All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`: + +- `record: record_create(record: { table: "...", properties: [...] }) { id }` +- `record: record_update(id: $id, record: { properties: [...] }) { id }` +- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table" + +### Soft Delete vs Hard Delete + +**Soft delete** (default) — sets `deleted_at` timestamp: +```graphql +mutation { + record_delete(table: "article", id: "123") { + id + deleted_at # Timestamp is set + } +} +``` + +**Hard delete** (permanent) — requires `hard_delete: true`: +```graphql +mutation { + record_delete(table: "article", id: "123", hard_delete: true) { + id + } +} +``` + +Soft-deleted records can be queried using the `deleted_at` filter: +```graphql +query { + records( + filter: { + table: { value: "article" } + deleted_at: { exists: true } + } + ) { + results { id deleted_at } + } +} +``` + +### Pagination Component + +```liquid +{% graphql result = 'products/search', page: context.params.page %} +{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %} +``` + +--- + +## 8. Schema + +Schema files define database tables in YAML at `app/schema/`. + +```yaml +# app/schema/article.yml +name: article +properties: + - name: title + type: string + - name: body + type: text + - name: published_at + type: datetime + - name: image + type: upload + options: + public: true + versions: + - name: thumbnail + resize: "200x200>" + - name: medium + resize: "800x600>" +``` + +### Property Types + +`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload` + +### Upload Options + +| Option | Type | Description | +|--------|------|-------------| +| `public` | boolean | `true` = public URL, `false` = requires auth | +| `max_size` | integer | Max file size in bytes | +| `versions` | array | Image resize versions | +| `extensions` | array | Allowed file extensions | + +Version resize syntax: +- `100x100>` — Resize only if larger (downscale only) +- `100x100<` — Resize only if smaller (upscale only) +- `100x100#` — Exact dimensions (may crop) +- `100x100^` — Minimum dimensions (may crop) +- `100x100` — Fit within dimensions + +### Reserved Names (MUST NOT Use) + +The following names are reserved by platformOS and MUST NOT be used as custom table or property names: + +**System fields (automatically created on every record):** +- `id` — Record UUID +- `created_at` — Creation timestamp +- `updated_at` — Last update timestamp +- `deleted_at` — Soft delete timestamp +- `type_name` — Table name +- `properties` — Property container + +**Reserved table names:** +- `user`, `users` — Built-in User table +- `session`, `sessions` — Session management +- `record`, `records` — Record operations +- `constant`, `constants` — System constants +- `table`, `tables` — Table metadata +- `background_job`, `background_jobs` — Background job system + +--- + +## 9. Liquid Reference + +### Tags + +```liquid +{% graphql result = 'query_name', arg: value %} +{% function result = 'path/to/partial', arg: value %} +{% render 'partial', var: value %} +{% doc %} @param name {Type} - description {% enddoc %} +{% return result %} +{% export my_var, namespace: 'my_ns' %} +{% parse_json data %}{"key": "value"}{% endparse_json %} +{% redirect_to '/path', status: 302 %} +{% session key = value %} +{% log variable, type: 'debug' %} +{% cache key: 'key_name', expire: 3600 %}...{% endcache %} +{% background source_name: 'job_name', priority: 'low', delay: 5.0, max_attempts: 3 %}...{% endbackground %} +{% content_for_layout %} +{% theme_render_rc 'modules/common-styling/toasts' %} +``` + +**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is). + +### Output + +```liquid +{{ variable }} +{{ variable | html_safe }} +{% print variable %} +``` + +### Common Filters + +- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by` +- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys` +- **Dates:** `add_to_time`, `localize`, `is_date_in_past` +- **Validation:** `is_email_valid`, `is_json_valid` +- **Encoding:** `json`, `base64_encode`, `url_encode` + +### Coding Standards + +You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line. + +**Correct:** +```liquid +{% liquid + assign filtered = products | where: 'available', true | map: 'title' | first + assign price = product | where: 'id', pid | map: 'price' | first +%} +``` + +**WRONG (causes syntax errors):** +```liquid +{% liquid + assign filtered = products + | where: 'available', true + | map: 'title' + | first +%} +``` + +--- + +## 10. Global Context + +**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results. + +| Property | Description | +|----------|-------------| +| `context.params` | HTTP parameters (query string + body) | +| `context.session` | Server-side session storage | +| `context.location` | URL info (`pathname`, `search`, `host`) | +| `context.environment` | `staging` or `production` | +| `context.is_xhr` | `true` for AJAX requests | +| `context.authenticity_token` | CSRF token | +| `context.constants` | Environment constants (hidden from `{{ context }}` for security) | +| `context.page.metadata` | Page metadata from front matter | + +### context.current_user + +`context.current_user` is a documented platformOS object that returns basic data of the currently logged-in user: + +```liquid +{{ context.current_user.id }} # User UUID +{{ context.current_user.email }} # User email +{{ context.current_user.first_name }} # First name +{{ context.current_user.last_name }} # Last name +{{ context.current_user.slug }} # User slug +{{ context.current_user.properties }} # Custom properties hash +``` + +Returns `null` if no user is logged in. + +For projects using pos-module-user, prefer `modules/user/queries/user/current` as it provides additional normalized user data and role information. Use `context.current_user` for simple checks (e.g., checking if anyone is logged in) and the User Module query for full user data operations. + +--- + +## 11. User Module (Authentication & Authorization) + +You MUST use the User Module for all authentication and authorization. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. + +### Built-in Roles + +- **Anonymous** — unauthenticated users +- **Authenticated** — any logged-in user +- **Superadmin** — bypasses ALL permission checks + +### Authorization Helpers + +```liquid +{% function profile = 'modules/user/queries/user/current' %} + +{% comment %} Check permission (returns true/false) {% endcomment %} +{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %} + +{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %} + +{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %} +{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %} +``` + +> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`. + +### Custom Permissions + +Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`: + +```bash +mkdir -p app/modules/user/public/lib/queries/role_permissions +cp modules/user/public/lib/queries/role_permissions/permissions.liquid \ + app/modules/user/public/lib/queries/role_permissions/permissions.liquid +``` + +Define roles: +```liquid +{% parse_json data %} +{ + "admin": ["admin.view", "users.manage"], + "editor": ["article.create", "article.update"], + "superadmin": [] +} +{% endparse_json %} +{% return data %} +``` + +### Native Authorization Policies (Optional) + +platformOS also provides `authorization_policies/` for page and form-level access control. These work independently of the User Module and are useful for simple checks: + +**File:** `app/authorization_policies/requires_login.liquid` +```liquid +--- +name: requires_login +redirect_to: /sign-in +flash_alert: Please sign in to access this page +--- +{% if context.current_user %}true{% else %}false{% endif %} +``` + +**Usage in page front matter:** +```liquid +--- +slug: admin/dashboard +authorization_policies: + - requires_login +--- +``` + +For projects using pos-module-user, prefer the module's authorization helpers. Use native authorization policies only for simple use cases not covered by the module. + +--- + +## 12. Core Module + +You MUST use pos-module-core for commands, events, and validators. + +--- + +## 13. Common Styling + +You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components. + +### Setup + +```liquid +{% comment %} In {% endcomment %} +{% render 'modules/common-styling/init' %} +``` +```html + +``` + +### File Upload Component + +```liquid +{% render 'modules/common-styling/forms/upload', + id: 'image', presigned_upload: presigned, name: 'image', + allowed_file_types: ['image/*'], max_number_of_files: 5 +%} +``` + +--- + +## 14. Translations (i18n) + +You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. +The YAML file require top-level language key: + +``` +en: + app: + contact_form: + title: "..." +``` + +--- + +## 15. Forms + +You MUST use HTML `` tags. You MUST NOT use `{% form %}`. + +Forms MUST include the CSRF token: +```html + +``` + +For PUT/DELETE, forms MUST use POST with a `_method` hidden field: +```html + + + + + +``` + +Form fields MUST use bracket notation for resource binding: +```html + +``` + +Access in page: `context.params.resource` + +HTML forms submit checkbox values as "on" (string), but GraphQL expects boolean field to be Boolean type, not string. + +### Form Configurations (app/forms/) + +platformOS also supports form configurations in `app/forms/` that define validation, callbacks, and processing. These are YAML + Liquid files: + +```liquid +--- +name: contact_form +resource: contact_message +resource_owner: anyone +redirect_to: /contact/thank-you +flash_notice: Message sent successfully! +fields: + properties: + name: + validation: + presence: true + email: + validation: + presence: true + email: true +--- + +{% form %} + + + +{% endform %} +``` + +The `{% form %}` tag automatically generates the `
` element with correct attributes and CSRF token. It also provides the `form` object with field metadata. + +When using the Core Module command pattern (recommended), use HTML forms with bracket notation. The `{% form %}` tag is available for simpler use cases. + +### Form Validation Error Display + +```liquid +{% if form.fields.properties.name.errors %} + {{ form.fields.properties.name.errors }} +{% endif %} +``` + +### Validation Types + +| Validation | Description | +|------------|-------------| +| `presence: true` | Field is required | +| `email: true` | Must be valid email format | +| `uniqueness: true` | Must be unique across records | +| `length: { minimum: 5, maximum: 100 }` | String length constraints | +| `numericality: { greater_than: 0 }` | Numeric range constraints | +| `confirmation: true` | Must match `_confirmation` field | +| `url: true` | Must be valid URL | + +--- + +## 16. Constants & Credentials + +You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`. + +### Setting Constants + +**Via CLI:** +```bash +pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev +pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev +pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev +``` + +**Via GraphQL:** +```graphql +mutation { + constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") { + name + } +} +``` + +### Accessing Constants in Liquid + +Constants are hidden from `{{ context }}` for security. You MUST access them explicitly: +```liquid +{{ context.constants.STRIPE_SK_KEY }} +{{ context.constants.API_BASE_URL }} +``` + +### Naming Conventions + +| Use Case | Example | +|----------|---------| +| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` | +| API URLs | `API_BASE_URL` | +| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` | + +Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically. + +--- + +## 17. Flash Messages & Toasts + +### Layout Setup (before ``) + +```liquid +{% liquid + function flash = 'modules/core/commands/session/get', key: 'sflash' + if context.location.pathname != flash.from or flash.force_clear + function _ = 'modules/core/commands/session/clear', key: 'sflash' + endif + render 'modules/common-styling/toasts', params: flash +%} +``` + +### Liquid Usage + +```liquid +{% liquid + function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname + redirect_to '/orders' +%} +``` + +### JavaScript Usage + +```javascript +new pos.modules.toast('success', 'Saved!'); +new pos.modules.toast('error', 'Failed'); +``` + +--- + +## 18. Notifications (Email/SMS) + +```liquid +{% comment %} app/emails/order_confirmation.liquid {% endcomment %} +--- +to: {{ data.email }} +from: shop@example.com +subject: "Order #{{ data.order_id }}" +layout: mailer +--- +

Thank you for your order!

+``` + +Emails SHOULD be sent asynchronously using events + consumers. + +--- + +## 19. Payments (Stripe) + +### Install + +```bash +pos-cli modules install payments && pos-cli modules install payments_stripe +pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev +``` + +### Create Transaction + +```liquid +{% function transaction = 'modules/payments/commands/transactions/create', + gateway: 'stripe', email: email, line_items: items, + success_url: '/thank-you', cancel_url: '/cart' +%} +{% function url = 'modules/payments/queries/pay_url', transaction: transaction %} +{% redirect_to url, status: 303 %} +``` + +Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed` + +**Test card:** `4242 4242 4242 4242`, any future date, any CVC. + +--- + +## 20. Background Jobs + +Background jobs run code asynchronously outside the HTTP request cycle. + +### Syntax + +```liquid +{% background + source_name: 'send_welcome_email', + delay: 5.0, + priority: 'default', + max_attempts: 3 +%} + {% graphql user = 'users/find', id: user_id %} + {% graphql _ = 'emails/send_welcome', email: user.email %} +{% endbackground %} +``` + +### Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `source_name` | String | — | Human-readable job identifier | +| `priority` | String | `default` | `high` (1min), `default` (5min), `low` (60min) | +| `delay` | Float | 0 | Minutes to delay execution | +| `max_attempts` | Integer | 1 | Retry count (1-5) | + +### CRITICAL: Variable Scope + +Only variables **explicitly passed** to the background tag are available inside it. The `context` object is available by default but with limitations. + +**WRONG:** +```liquid +{% assign user_id = context.current_user.id %} +{% background source_name: 'job' %} + {{ user_id }} {# nil — not passed #} +{% endbackground %} +``` + +**CORRECT:** +```liquid +{% assign user_id = context.current_user.id %} +{% background source_name: 'job', user_id: user_id %} + {{ user_id }} {# Works! Explicitly passed #} +{% endbackground %} +``` + +### Priority Levels & Execution Limits + +| Priority | Max Execution | Use Case | +|----------|---------------|----------| +| `high` | 1 minute | Critical, time-sensitive tasks | +| `default` | 5 minutes | Standard operations | +| `low` | 60 minutes | Heavy processing, batch jobs | + +### Monitoring Jobs + +```graphql +query { + background_jobs( + per_page: 20 + sort: [{ created_at: { order: DESC } }] + ) { + results { + id + source_name + priority + attempts + max_attempts + created_at + started_at + completed_at + failed_at + error_message + } + } +} +``` + +### Payload Limits + +Keep background job payloads under 100KB. For large data, pass references (IDs) and fetch data inside the job: + +```liquid +{% background record_id: record_id, source_name: 'process' %} + {% graphql record = 'records/find', id: record_id %} + {# Process the record #} +{% endbackground %} +``` + +--- + +## 21. Migrations + +Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications. + +### File Structure + +``` +app/migrations/ +├── 20240115120000_seed_initial_data.liquid +├── 20240116093000_add_default_categories.liquid +└── 20240120150000_init_staging_constants.liquid +``` + +Files MUST be named with UTC timestamp prefix for chronological execution. + +### Creating a Migration + +```bash +pos-cli migrations generate dev init_staging_constants +# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid +``` + +### Example: Initialize Staging Constants + +```liquid +{% liquid + if context.environment == 'staging' + graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123' + graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com' + endif +%} +``` + +### Example: Seed Data + +```liquid +{% parse_json categories %} +["Electronics", "Clothing", "Books"] +{% endparse_json %} + +{% for category in categories %} + {% graphql _ = 'categories/create', name: category %} +{% endfor %} +``` + +### Running Migrations + +- **Automatic:** Pending migrations run on `pos-cli deploy` +- **Manual:** `pos-cli migrations run TIMESTAMP dev` + +### Migration States + +- **pending** — not yet executed (runs on next deploy) +- **done** — successfully completed (will not run again) +- **error** — failed (can edit and retry) + +### Migration Best Practices + +1. **Make migrations idempotent** — running twice should not cause errors: +```liquid +{% graphql record = 'records/find', id: record_id %} +{% unless record.properties.status %} + {% graphql _ = 'records/update', id: record_id, status: 'active' %} +{% endunless %} +``` + +2. **Use background jobs for large migrations:** +```liquid +{% background source_name: 'data_migration', priority: 'low' %} + {% graphql records = 'records/list_all' %} + {% for record in records.records.results %} + {# Process each record #} + {% endfor %} +{% endbackground %} +``` + +3. **Test migrations on staging first** +4. **Log progress:** +```liquid +{% log 'Migration started' %} +{% log 'Processed 50 records' %} +``` + +For large data imports, use Data Import/Export instead of migrations. + +--- + +## 22. Data Import/Export + +### Exporting Data + +```bash +# Export all data +pos-cli data export staging --path=./export.json + +# Export specific tables +pos-cli data export staging --tables=products,orders --path=./products.json +``` + +### Importing Data + +```bash +# Import data +pos-cli data import staging ./export.json + +# Import with transformations +pos-cli data import staging ./data.json --transform=./transform.js +``` + +### Export Format + +```json +{ + "users": [ + { + "id": "123", + "email": "user@example.com", + "properties": { "first_name": "John" } + } + ], + "records": { + "product": [ + { + "id": "456", + "properties": { "name": "Widget", "price": 19.99 } + } + ] + } +} +``` + +### Cleaning Instance Data + +```bash +# WARNING: Deletes all data! +pos-cli data clean staging + +# Clean specific tables +pos-cli data clean staging --tables=products,orders +``` + +--- + +## 23. JSON Documents + +JSON Documents provide schemaless data storage for flexible, document-based data. + +**Use Cases:** Configuration data, unstructured content, temporary data storage. + +### Creating JSON Documents + +```graphql +mutation { + json_document_create( + document: { + name: "site_config" + content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}" + } + ) { + id + name + content + } +} +``` + +### Querying + +```graphql +query { + json_document(name: "site_config") { + id + name + content + } + + json_documents(per_page: 10) { + results { id name content } + } +} +``` + +### Updating + +```graphql +mutation { + json_document_update( + name: "site_config" + document: { content: "{\"theme\": \"light\"}" } + ) { + id + content + } +} +``` + +### Using in Liquid + +```liquid +{% graphql config = 'json_documents/find', name: 'site_config' %} +{% assign settings = config.json_document.content | parse_json %} +Theme: {{ settings.theme }} +``` + +--- + +## 24. Activity Feeds + +Activity Feeds implement the W3C Activity Streams 2.0 specification for tracking user activities. + +**Characteristics:** Activities are immutable (append-only), each has a unique UUID. + +### Creating Activities + +```graphql +mutation { + activity_create( + activity: { + type: "Join" + actor: { type: "Person", id: "User.123", name: "John" } + object: { type: "Group", id: "Group.456" } + } + ) { + id + uuid + } +} +``` + +### Publishing to Feeds + +```graphql +mutation { + feed_publish( + feed_id: "user_123_notifications" + activity_uuid: "abc-123-uuid" + ) { id } +} +``` + +### Querying Feeds + +```graphql +query { + feeds(feed_id: "user_123_notifications", per_page: 20) { + total_entries + results { id uuid type actor object target created_at } + } +} +``` + +### Common Activity Types + +| Type | Description | +|------|-------------| +| `Create` | Created something | +| `Update` | Updated something | +| `Delete` | Deleted something | +| `Join` | Joined a group | +| `Follow` | Started following | +| `Like` | Liked content | +| `Comment` | Commented | +| `Approve` | Approved a request | + +--- + +## 25. AI Embeddings + +platformOS supports AI embeddings for semantic search and similarity matching. + +### Creating Embeddings + +```graphql +mutation { + embedding_create( + embedding: { + name: "product_description" + value: "High-quality wireless headphones" + target_id: "product_123" + target_type: "Product" + } + ) { + id + vector + } +} +``` + +### Semantic Search + +```graphql +query { + embeddings_search( + query: "wireless audio devices" + limit: 10 + threshold: 0.7 + ) { + results { + id + target_id + similarity + value + } + } +} +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| `name` | Embedding type identifier | +| `value` | Text to embed | +| `target_id` | Associated entity ID | +| `target_type` | Associated entity type | + +--- + +## 26. Testing + +Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. + +Every new feature MUST have unit tests for commands. + +```liquid +{% function result = 'commands/products/create', title: "Test" %} +{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %} +{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %} +{% return contract %} +``` + +Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. + +--- + +## 27. CLI Commands + +```bash +# Deployment +pos-cli deploy dev + +# Sync (MUST sync every file after modification) +pos-cli sync dev + +# Logs +pos-cli logs dev + +# Linting (MUST run after EVERY file change) +platformos-check + +# Run Liquid inline +pos-cli exec liquid dev '' + +# Run GraphQL inline +pos-cli exec graphql dev '' + +# Tests +pos-cli test run staging + +# Modules +pos-cli modules install +pos-cli modules download + +# Constants +pos-cli constants set --name KEY --value "value" dev + +# Generate CRUD +pos-cli generate run modules/core/generators/crud --include-views + +# Migrations +pos-cli migrations generate dev +pos-cli migrations run TIMESTAMP dev + +# Data Import/Export +pos-cli data export staging --path=./export.json +pos-cli data import staging ./data.json +pos-cli data clean staging +``` + +--- + +## 28. Modules Reference + +| Module | Install | Purpose | Required | +|--------|---------|---------|----------| +| `core` | Required | Commands, events, validators | YES | +| `user` | Required | Auth, RBAC, OAuth2 | YES | +| `common-styling` | Required | CSS, components | YES | +| `tests` | Optional | Testing framework | YES (for testing) | +| `payments` + `payments_stripe` | Optional | Stripe payments | No | +| `chat` | Optional | WebSocket messaging | No | +| `openai` | Optional | OpenAI integration | No | + +--- + +## 29. Forbidden Behaviors + +You MUST NOT: +- Edit files in `./modules/` (read-only) +- Break long lines in `{% liquid %}` blocks (causes syntax errors) +- Invent Liquid tags, filters, or GraphQL types that do not exist +- Bypass security (CSRF tokens, authorization) +- Access databases directly outside GraphQL +- Deploy without running `platformos-check` +- Sync files outside `./app/` +- Hardcode API keys, secrets, or environment-specific URLs +- Hardcode user-facing text in partials (use translations) +- Put HTML, JS, or CSS in page files +- Call GraphQL from partials +- Put raw GraphQL in pages (use `.graphql` files) +- Create or modify application files outside the `app/` directory +- Use reserved names (`id`, `created_at`, `deleted_at`, `type_name`, `properties`) as custom property/table names + +--- + +## 30. Pre-Flight Checklist + +Before every change, verify: + +- [ ] No underscore prefix in partial filenames +- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid` +- [ ] Pages have ONE HTTP method each +- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files) +- [ ] No HTML/JS/CSS in pages +- [ ] No hardcoded text in partials (use translations) +- [ ] `platformos-check` passes with 0 errors +- [ ] Every file synced after modification +- [ ] All list queries support pagination (`per_page`, `page`) +- [ ] All inputs validated in commands before persisting +- [ ] CSS/JS minified, `asset_url` used for cache busting + +### Asset URL Usage + +```liquid +{{ 'images/img.png' | asset_url }} +``` diff --git a/src/http-server.js b/src/http-server.js index c0bdea4..6537e3d 100644 --- a/src/http-server.js +++ b/src/http-server.js @@ -11,7 +11,7 @@ import { buildDashboardHtml } from './dashboard.js'; import { getProjectMap } from './tools/project-map.js'; import { buildDependencyGraph } from './core/dependency-graph.js'; import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory, ruleDrilldown } from './core/analytics-queries.js'; -import { ruleScores, suggestedRules, retrieveCasesByCheck, generateRuleTemplate } from './core/case-base.js'; +import { ruleScores, suggestedRules, retrieveCasesByCheck, generateRuleTemplate, synthesizeGuardPredicate } from './core/case-base.js'; import { addPromotedRule, removePromotedRule, listPromotedRules } from './core/rules/promoted-rules.js'; import { reloadRules, loadAllRules } from './core/rules/index.js'; import { runRules, getDisabledRules, getAllChecksWithRules, getRulesForCheck } from './core/rules/engine.js'; @@ -22,7 +22,7 @@ import { buildFactGraph } from './core/project-fact-graph.js'; * HTTP server — REST endpoints for tool discovery, execution, and resources. * MCP protocol (JSON-RPC over stdio) is handled by the SDK transport in server.js. */ -export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild }) { +export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild, switchEngineMode, getEngineMode }) { if (!port) return null; const dashboardHtml = buildDashboardHtml(); @@ -89,6 +89,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re return handleGetSuppressions(projectDir, res); } + if (method === 'GET' && url.pathname === '/api/engine/mode') { + return sendJson(res, 200, { mode: getEngineMode?.() ?? 'static' }); + } + if (method === 'GET' && url.pathname === '/api/sessions') { return handleGetSessions(sessionsDir, res); } @@ -149,6 +153,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re return handlePromoteRule(projectDir, body, res); } + if (url.pathname === '/api/engine/mode') { + return handleSetEngineMode(switchEngineMode, body, log, res); + } + if (url.pathname === '/api/health-score') { return handlePostHealthScore(analyticsStore, body, res); } @@ -553,6 +561,23 @@ async function handleGetDependencyTree(projectDir, getStatus, res) { } } +// ── Engine mode handler ───────────────────────────────────────────────────── + +function handleSetEngineMode(switchEngineMode, body, log, res) { + if (!switchEngineMode) return sendJson(res, 503, { error: 'Engine mode switching not available' }); + const { mode } = body ?? {}; + if (!mode || (mode !== 'adaptive' && mode !== 'static')) { + return sendJson(res, 400, { error: 'Invalid mode. Must be "adaptive" or "static".' }); + } + try { + const newMode = switchEngineMode(mode); + log?.(`engine-mode: switched to ${newMode} via HTTP`); + sendJson(res, 200, { mode: newMode }); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + // ── Promoted rules handlers (Phase J) ───────────────────────────────────── function handleGetPromotedRules(projectDir, res) { @@ -1074,10 +1099,14 @@ function handleRuleDrilldown(analyticsStore, url, res) { function handleSuggestedRules(analyticsStore, res) { if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); try { - const suggestions = suggestedRules(analyticsStore).map(s => ({ - ...s, - template: generateRuleTemplate(s), - })); + const suggestions = suggestedRules(analyticsStore).map(s => { + const guards = synthesizeGuardPredicate(analyticsStore, s.check, s.template_fp); + return { + ...s, + when: guards, + template: generateRuleTemplate(s, guards), + }; + }); sendJson(res, 200, { suggestions }); } catch (e) { sendJson(res, 500, { error: e.message }); diff --git a/src/server.js b/src/server.js index ef8451a..e4444d3 100644 --- a/src/server.js +++ b/src/server.js @@ -15,7 +15,8 @@ import { invalidateProjectMap } from './tools/project-map.js'; import { createToolRegistry } from './tools.js'; import { initPromotedRules, reloadRules } from './core/rules/index.js'; import { updateDisabledRules } from './core/rules/engine.js'; -import { ruleScores } from './core/case-base.js'; +import { ruleScores, resolveProbation } from './core/case-base.js'; +import { loadEngineMode, isAdaptive, setEngineMode, getEngineMode } from './core/engine-mode.js'; import { startHttp } from './http-server.js'; import { createLogger } from './core/logger.js'; import { LSP_READY_TIMEOUT_MS } from './core/constants.js'; @@ -75,10 +76,14 @@ export async function createServer({ projectDir, httpPort = 0 }) { log(`analytics-store: failed to open (${e.message}); analytics will not be available`); } + // ── Engine mode (adaptive vs static) ────────────────────────────────────── + const engineMode = loadEngineMode(projectDir); + log(`engine-mode: ${engineMode}`); + // ── Promoted rules (Phase J — declarative rules from analytics) ────────────── try { initPromotedRules(projectDir); - log('promoted-rules: loaded'); + log(`promoted-rules: ${isAdaptive() ? 'loaded' : 'skipped (static mode)'}`); } catch (e) { log(`promoted-rules: failed to load (${e.message})`); } @@ -111,6 +116,10 @@ export async function createServer({ projectDir, httpPort = 0 }) { // ── Disabled rule enforcement (Phase J4) ───────────────────────────────────── function syncDisabledRules() { + if (!isAdaptive()) { + updateDisabledRules(null); + return; + } if (!analyticsStore) return; try { const scores = ruleScores(analyticsStore, { minEmitted: 5 }); @@ -123,6 +132,26 @@ export async function createServer({ projectDir, httpPort = 0 }) { } syncDisabledRules(); + // ── Engine mode transitions ────────────────────────────────────────────────── + function handleModeTransition(prev, mode) { + log(`engine-mode: ${prev} → ${mode}`); + reloadRules(projectDir); + if (mode === 'adaptive') { + syncDisabledRules(); + if (analyticsStore) { + try { resolveProbation(analyticsStore); } catch {} + } + } else { + updateDisabledRules(null); + } + broadcastSse({ event: 'engine_mode_changed', ts: new Date().toISOString(), prev, mode }); + } + + function switchEngineMode(mode) { + setEngineMode(mode, { projectDir, onTransition: handleModeTransition }); + return getEngineMode(); + } + // ── In-memory session stats (not written to JSONL to keep log entries small) ── const sessionStats = { byTool: {}, // tool → { calls, errors, totalMs } @@ -570,6 +599,8 @@ export async function createServer({ projectDir, httpPort = 0 }) { analyticsStore, log, emit, + switchEngineMode, + getEngineMode, }; // ── Create MCP server (SDK) for stdio transport ─────────────────────────── @@ -664,10 +695,11 @@ export async function createServer({ projectDir, httpPort = 0 }) { hintEffectiveness: session.hintEffectiveness, pipelineTraces: [...session.pipelineTraces.entries()].map(([path, trace]) => ({ path, trace })), analytics: analyticsStore ? analyticsStore.stats() : null, + engineMode: getEngineMode(), }; } const dataRoot = join(__dirname, 'data'); - startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild: syncDisabledRules }); + startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild: syncDisabledRules, switchEngineMode, getEngineMode }); } // ── Graceful shutdown ───────────────────────────────────────────────────── diff --git a/src/tools.js b/src/tools.js index f3b8b1f..f0eccab 100644 --- a/src/tools.js +++ b/src/tools.js @@ -69,15 +69,30 @@ export function createToolRegistry(ctx, mcpServer = null) { // Wrap handler with timing telemetry + session tracking const timedHandler = async (args) => { + // Dashboard-originated calls (e.g. Live Diagnostic Console) must NOT + // pollute agent-activity surfaces: File Validation Map, Activity log, + // tool stats, bigram sequences, or NDJSON session log. The sentinel is + // stripped before the raw handler runs so tool logic never sees it. + const untracked = args?._source === 'dashboard_live'; + let cleanArgs = args; + if (args && typeof args === 'object' && '_source' in args) { + const { _source, ...rest } = args; + cleanArgs = rest; + } + + if (untracked) { + return rawHandler(cleanArgs); + } + const start = Date.now(); let success = true; try { - const result = await rawHandler(args); + const result = await rawHandler(cleanArgs); const durationMs = Date.now() - start; - ctx.emit?.('tool_call', { tool: tool.name, durationMs, success, input: args, output: result }); + ctx.emit?.('tool_call', { tool: tool.name, durationMs, success, input: cleanArgs, output: result }); // Session tracking (non-blocking, best-effort) - try { updateSession(ctx.session, tool.name, args, result); } catch (e) { ctx.log?.(`Session tracking error: ${e.message}`); } + try { updateSession(ctx.session, tool.name, cleanArgs, result); } catch (e) { ctx.log?.(`Session tracking error: ${e.message}`); } // Tool avoidance detection: if there's a validated plan with unvalidated files // and the agent is calling tools other than validation, add an advisory note @@ -98,7 +113,7 @@ export function createToolRegistry(ctx, mcpServer = null) { } catch (e) { success = false; const durationMs = Date.now() - start; - ctx.emit?.('tool_call', { tool: tool.name, durationMs, success, input: args, error: e.message }); + ctx.emit?.('tool_call', { tool: tool.name, durationMs, success, input: cleanArgs, error: e.message }); throw e; } }; diff --git a/src/tools/server-status.js b/src/tools/server-status.js index bd98d78..c29895e 100644 --- a/src/tools/server-status.js +++ b/src/tools/server-status.js @@ -1,5 +1,6 @@ import { VALID_DOMAINS } from '../core/domain-detector.js'; import { ruleScores } from '../core/case-base.js'; +import { getEngineMode } from '../core/engine-mode.js'; export const serverStatusTool = { name: 'server_status', @@ -20,6 +21,7 @@ export const serverStatusTool = { return { server: 'pos-supervisor', version: ctx.version, + engine_mode: getEngineMode(), project_dir: ctx.directory, pos_cli: { found: ctx.posCliFound ?? false, diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js index 622a9ae..374a31c 100644 --- a/src/tools/validate-code.js +++ b/src/tools/validate-code.js @@ -9,11 +9,12 @@ import { getDomainFromPath, getDomainHeader } from '../core/domain-detector.js'; import { getTriggeredGotchas, getContentTriggers } from '../core/knowledge-loader.js'; import { generateStructuralWarnings } from '../core/structural-warnings.js'; import { validateSchema } from '../core/schema-validator.js'; +import { validateTranslationYaml } from '../core/translation-validator.js'; import { checkSchemaProperties } from '../core/schema-property-checker.js'; import { runDiagnosticPipeline } from '../core/diagnostic-pipeline.js'; import { partitionCallersByPending } from '../core/pending-callers.js'; import { toUri, sanitizePath } from '../core/utils.js'; -import { fingerprint, templateFingerprint, messageTemplate } from '../core/diagnostic-record.js'; +import { fingerprint, templateFingerprint, messageTemplate, extractParams } from '../core/diagnostic-record.js'; import { getProjectMap } from './project-map.js'; import { buildFactGraph } from '../core/project-fact-graph.js'; import { loadAllRules } from '../core/rules/index.js'; @@ -145,6 +146,7 @@ explicitly only if you are validating a file that is NOT part of the most recent const isLiquid = file_path.endsWith('.liquid'); const isGraphql = file_path.endsWith('.graphql'); const isSchema = file_path.endsWith('.yml') && /(?:^|\/)app\/schema\//.test(file_path); + const isTranslationYaml = /\.ya?ml$/.test(file_path) && /(?:^|\/)app\/translations\//.test(file_path); const result = { errors: [], @@ -308,6 +310,21 @@ explicitly only if you are validating a file that is NOT part of the most recent } } + // 2b1. Translation YAML structural validation — catches the missing + // top-level locale key case (`app:` at root instead of `en: → app:`). + // The LSP won't flag this because the YAML parses fine, but every + // `{{ 'key' | t }}` lookup will silently return the raw key. Runs before + // the GraphQL/structural branches so the error lands on the file itself. + if (isTranslationYaml) { + try { + const transResult = validateTranslationYaml(content, file_path); + result.errors.push(...transResult.errors); + result.warnings.push(...transResult.warnings); + } catch (e) { + result.infos.push({ check: 'translation-validator', severity: 'info', message: `Translation validation failed: ${e.message}` }); + } + } + // 2b2. Schema property cross-check (GraphQL files only) if (isGraphql) { try { @@ -510,6 +527,20 @@ explicitly only if you are validating a file that is NOT part of the most recent result.proposed_fixes = proposedFixes; + // Merge rule-generated fixes into proposed_fixes + for (const d of allDiagnostics) { + if (d.fixes?.length > 0) { + for (const f of d.fixes) { + result.proposed_fixes.push({ + ...f, + source: 'rule', + rule_id: d.rule_id ?? null, + check: d.check ?? null, + }); + } + } + } + // Attach per-diagnostic fix field for (const [diagIdx, fix] of diagnosticFixes) { const d = allDiagnostics[diagIdx]; @@ -672,6 +703,7 @@ explicitly only if you are validating a file that is NOT part of the most recent new_text_hash: ctx.blobStore ? ctx.blobStore.put(f.newText || '') : '', kind: f.kind || 'unknown', })); + const diagParams = extractParams(d.check, d.message || ''); ctx.sessionBus.emit('validator_emit', { fp, template_fp: tFp, @@ -682,6 +714,7 @@ explicitly only if you are validating a file that is NOT part of the most recent hint_rule_id: d.rule_id || d.check || null, confidence: d.confidence ?? null, proposed_fixes: fixes, + params: Object.keys(diagParams).length > 0 ? diagParams : undefined, }); } } catch { /* best-effort telemetry */ } diff --git a/tests/fixtures/project/app/views/pages/test.html.liquid b/tests/fixtures/project/app/views/pages/test.html.liquid new file mode 100644 index 0000000..34de38f --- /dev/null +++ b/tests/fixtures/project/app/views/pages/test.html.liquid @@ -0,0 +1,6 @@ +--- +slug: my-page +--- +{% render 'shared/header' %} +{{ 'greeting' | t }} +{% graphql g = 'products/search' %} \ No newline at end of file diff --git a/tests/unit/case-base-integration.test.js b/tests/unit/case-base-integration.test.js index c939b0b..561df42 100644 --- a/tests/unit/case-base-integration.test.js +++ b/tests/unit/case-base-integration.test.js @@ -1,6 +1,7 @@ -import { describe, it, expect, beforeEach } from 'bun:test'; +import { describe, it, expect, beforeEach, afterEach } from 'bun:test'; import { registerRules, clearRules, runRules } from '../../src/core/rules/engine.js'; import { buildFactGraph } from '../../src/core/project-fact-graph.js'; +import { setEngineMode, resetEngineMode } from '../../src/core/engine-mode.js'; function buildMinimalGraph() { return buildFactGraph({ @@ -24,9 +25,12 @@ const testRule = { describe('Phase H: Case-base scoring in rule engine', () => { beforeEach(() => { + resetEngineMode(); + setEngineMode('adaptive'); clearRules(); registerRules([testRule]); }); + afterEach(() => { resetEngineMode(); }); it('runs without analytics store (no scoring applied)', () => { const graph = buildMinimalGraph(); diff --git a/tests/unit/engine-mode.test.js b/tests/unit/engine-mode.test.js new file mode 100644 index 0000000..b37123b --- /dev/null +++ b/tests/unit/engine-mode.test.js @@ -0,0 +1,179 @@ +import { describe, it, expect, beforeEach, afterEach } from 'bun:test'; +import { mkdtempSync, rmSync, readFileSync, existsSync, mkdirSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { + getEngineMode, setEngineMode, isAdaptive, + loadEngineMode, persistEngineMode, resetEngineMode, + onEngineModeChange, +} from '../../src/core/engine-mode.js'; +import { + registerRule, clearRules, runRules, + updateDisabledRules, getDisabledRules, +} from '../../src/core/rules/engine.js'; + +let tmpDir; + +beforeEach(() => { + resetEngineMode(); + clearRules(); + updateDisabledRules([]); + tmpDir = mkdtempSync(join(tmpdir(), 'engine-mode-test-')); + mkdirSync(join(tmpDir, '.pos-supervisor'), { recursive: true }); +}); + +afterEach(() => { + resetEngineMode(); + clearRules(); + updateDisabledRules([]); + rmSync(tmpDir, { recursive: true, force: true }); +}); + +describe('engine mode: core', () => { + it('defaults to static', () => { + expect(getEngineMode()).toBe('static'); + expect(isAdaptive()).toBe(false); + }); + + it('setEngineMode switches to adaptive', () => { + setEngineMode('adaptive'); + expect(getEngineMode()).toBe('adaptive'); + expect(isAdaptive()).toBe(true); + }); + + it('setEngineMode switches back to static', () => { + setEngineMode('adaptive'); + setEngineMode('static'); + expect(getEngineMode()).toBe('static'); + expect(isAdaptive()).toBe(false); + }); + + it('setEngineMode rejects invalid mode', () => { + expect(() => setEngineMode('turbo')).toThrow(/Invalid engine mode/); + }); + + it('setEngineMode is a no-op when mode unchanged', () => { + let callCount = 0; + onEngineModeChange(() => callCount++); + setEngineMode('static'); + expect(callCount).toBe(0); + }); +}); + +describe('engine mode: persistence', () => { + it('persistEngineMode writes JSON file', () => { + persistEngineMode(tmpDir, 'adaptive'); + const raw = JSON.parse(readFileSync(join(tmpDir, '.pos-supervisor', 'engine-mode.json'), 'utf-8')); + expect(raw.mode).toBe('adaptive'); + expect(raw.updated_at).toBeDefined(); + }); + + it('loadEngineMode reads from disk', () => { + persistEngineMode(tmpDir, 'adaptive'); + resetEngineMode(); + expect(getEngineMode()).toBe('static'); + + const mode = loadEngineMode(tmpDir); + expect(mode).toBe('adaptive'); + expect(getEngineMode()).toBe('adaptive'); + }); + + it('loadEngineMode returns static when file missing', () => { + const emptyDir = mkdtempSync(join(tmpdir(), 'engine-mode-empty-')); + const mode = loadEngineMode(emptyDir); + expect(mode).toBe('static'); + rmSync(emptyDir, { recursive: true, force: true }); + }); + + it('setEngineMode with projectDir persists to disk', () => { + setEngineMode('adaptive', { projectDir: tmpDir }); + const raw = JSON.parse(readFileSync(join(tmpDir, '.pos-supervisor', 'engine-mode.json'), 'utf-8')); + expect(raw.mode).toBe('adaptive'); + }); +}); + +describe('engine mode: listeners', () => { + it('onEngineModeChange fires on transition', () => { + const calls = []; + onEngineModeChange((mode, prev) => calls.push({ mode, prev })); + + setEngineMode('adaptive'); + setEngineMode('static'); + + expect(calls).toEqual([ + { mode: 'adaptive', prev: 'static' }, + { mode: 'static', prev: 'adaptive' }, + ]); + }); + + it('unsubscribe stops listener', () => { + let callCount = 0; + const unsub = onEngineModeChange(() => callCount++); + + setEngineMode('adaptive'); + expect(callCount).toBe(1); + + unsub(); + setEngineMode('static'); + expect(callCount).toBe(1); + }); + + it('listener errors are non-fatal', () => { + onEngineModeChange(() => { throw new Error('boom'); }); + expect(() => setEngineMode('adaptive')).not.toThrow(); + expect(getEngineMode()).toBe('adaptive'); + }); +}); + +describe('engine mode: onTransition callback', () => { + it('fires onTransition with prev and new mode', () => { + const transitions = []; + setEngineMode('adaptive', { + onTransition: (prev, mode) => transitions.push({ prev, mode }), + }); + expect(transitions).toEqual([{ prev: 'static', mode: 'adaptive' }]); + }); +}); + +describe('engine mode: case-base scoring gate', () => { + function makeRule(id) { + return { + id, + check: 'Test', + priority: 10, + when: () => true, + apply: () => ({ rule_id: id, hint_md: 'test', fixes: [], confidence: 0.5 }), + }; + } + + it('static mode skips case-base scoring (confidence unchanged)', () => { + registerRule(makeRule('Test.rule')); + const mockStore = { + queryOne: () => ({ emitted: 100 }), + query: () => [{ outcome: 'resolved', cnt: 90 }], + }; + + const result = runRules( + { check: 'Test', template_fp: 'abc123' }, + { analyticsStore: mockStore }, + ); + expect(result.confidence).toBe(0.5); + expect(result.case_base_signal).toBeUndefined(); + }); + + it('adaptive mode applies case-base scoring', () => { + setEngineMode('adaptive'); + registerRule(makeRule('Test.rule')); + const mockStore = { + queryOne: () => ({ emitted: 100 }), + query: () => [{ outcome: 'resolved', cnt: 90 }, { outcome: 'regressed', cnt: 5 }], + }; + + const result = runRules( + { check: 'Test', template_fp: 'abc123' }, + { analyticsStore: mockStore }, + ); + expect(result.confidence).toBeGreaterThan(0.5); + expect(result.case_base_signal).toBeDefined(); + }); +}); diff --git a/tests/unit/guard-synthesis.test.js b/tests/unit/guard-synthesis.test.js new file mode 100644 index 0000000..47e71e1 --- /dev/null +++ b/tests/unit/guard-synthesis.test.js @@ -0,0 +1,301 @@ +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { openAnalyticsStore } from '../../src/core/analytics-store.js'; +import { synthesizeGuardPredicate, generateRuleTemplate } from '../../src/core/case-base.js'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; + +function tmpPath() { + return join(tmpdir(), `pos-guard-synth-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.db`); +} + +function seedDiagnostics(store, rows) { + for (const d of rows) { + store.db.prepare(` + INSERT INTO diagnostics (fp, template_fp, session_id, file, check_name, severity, ts, hint_rule_id, suppressed) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + `).run( + d.fp, d.template_fp ?? 'tpl1', d.session_id ?? 'sess-1', + d.file ?? 'app/views/pages/index.html.liquid', + d.check_name ?? 'TestCheck', d.severity ?? 'error', + d.ts ?? '2026-04-20T10:00:00Z', d.hint_rule_id ?? null, d.suppressed ?? 0, + ); + } +} + +function seedEvents(store, rows) { + for (const e of rows) { + const payload = { + fp: e.fp, + template_fp: e.template_fp ?? 'tpl1', + file: e.file ?? 'app/views/pages/index.html.liquid', + check: e.check ?? 'TestCheck', + ...(e.params && Object.keys(e.params).length > 0 ? { params: e.params } : {}), + }; + store.db.prepare(` + INSERT INTO events (session_id, kind, ts, payload) + VALUES (?, ?, ?, ?) + `).run(e.session_id ?? 'sess-1', 'validator_emit', e.ts ?? '2026-04-20T10:00:00Z', JSON.stringify(payload)); + } +} + +describe('synthesizeGuardPredicate', () => { + let store, dbPath; + + beforeEach(() => { + dbPath = tmpPath(); + store = openAnalyticsStore(dbPath); + }); + afterEach(() => { store.close(); }); + + test('returns empty when object with no data', () => { + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when).toEqual({}); + }); + + test('returns empty when below minSamples', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'app/views/pages/a.liquid' }, + { fp: 'fp2', file: 'app/views/pages/b.liquid' }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1', { minSamples: 5 }); + expect(when).toEqual({}); + }); + + test('infers file_type when ≥80% share type', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'app/views/pages/a.liquid' }, + { fp: 'fp2', file: 'app/views/pages/b.liquid' }, + { fp: 'fp3', file: 'app/views/pages/c.liquid' }, + { fp: 'fp4', file: 'app/views/pages/d.liquid' }, + { fp: 'fp5', file: 'app/views/partials/e.liquid' }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.file_type).toBe('page'); + }); + + test('skips file_type when no dominant type', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'app/views/pages/a.liquid' }, + { fp: 'fp2', file: 'app/views/pages/b.liquid' }, + { fp: 'fp3', file: 'app/views/partials/c.liquid' }, + { fp: 'fp4', file: 'app/views/partials/d.liquid' }, + { fp: 'fp5', file: 'app/lib/commands/e.liquid' }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.file_type).toBeUndefined(); + }); + + test('skips file_type=unknown even if dominant', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'other/a.liquid' }, + { fp: 'fp2', file: 'other/b.liquid' }, + { fp: 'fp3', file: 'other/c.liquid' }, + { fp: 'fp4', file: 'other/d.liquid' }, + { fp: 'fp5', file: 'other/e.liquid' }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.file_type).toBeUndefined(); + }); + + test('infers param_equals when ≥90% identical', () => { + const events = []; + for (let i = 0; i < 10; i++) { + events.push({ + fp: `fp${i}`, + check: 'UndefinedObject', + params: { variable: i < 9 ? 'product' : 'collection' }, + }); + } + seedDiagnostics(store, events.map(e => ({ fp: e.fp, check_name: 'UndefinedObject' }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'UndefinedObject', 'tpl1'); + expect(when.param_equals).toEqual({ variable: 'product' }); + }); + + test('skips param_equals when below 90% threshold', () => { + const events = []; + for (let i = 0; i < 10; i++) { + events.push({ + fp: `fp${i}`, + check: 'UndefinedObject', + params: { variable: i < 8 ? 'product' : 'collection' }, + }); + } + seedDiagnostics(store, events.map(e => ({ fp: e.fp, check_name: 'UndefinedObject' }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'UndefinedObject', 'tpl1'); + expect(when.param_equals).toBeUndefined(); + }); + + test('infers param_startsWith when ≥80% share prefix', () => { + const events = [ + { fp: 'fp0', check: 'MissingPartial', params: { partial: 'modules/core/widget' } }, + { fp: 'fp1', check: 'MissingPartial', params: { partial: 'modules/core/header' } }, + { fp: 'fp2', check: 'MissingPartial', params: { partial: 'modules/core/footer' } }, + { fp: 'fp3', check: 'MissingPartial', params: { partial: 'modules/core/sidebar' } }, + { fp: 'fp4', check: 'MissingPartial', params: { partial: 'products/card' } }, + ]; + seedDiagnostics(store, events.map(e => ({ fp: e.fp, check_name: 'MissingPartial' }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'MissingPartial', 'tpl1'); + expect(when.param_startsWith).toBeDefined(); + expect(when.param_startsWith.partial).toBe('modules/core/'); + expect(when.param_equals).toBeUndefined(); + }); + + test('infers param_contains when ≥80% contain substring', () => { + const events = [ + { fp: 'fp0', check: 'UnknownFilter', params: { filter: 'asset_img_url' } }, + { fp: 'fp1', check: 'UnknownFilter', params: { filter: 'product_img_url' } }, + { fp: 'fp2', check: 'UnknownFilter', params: { filter: 'collection_img_url' } }, + { fp: 'fp3', check: 'UnknownFilter', params: { filter: 'variant_img_url' } }, + { fp: 'fp4', check: 'UnknownFilter', params: { filter: 'img_url' } }, + ]; + seedDiagnostics(store, events.map(e => ({ fp: e.fp, check_name: 'UnknownFilter' }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'UnknownFilter', 'tpl1'); + expect(when.param_contains).toBeDefined(); + expect(when.param_contains.filter).toBe('img_url'); + }); + + test('combines file_type and param guards', () => { + const events = []; + for (let i = 0; i < 6; i++) { + events.push({ + fp: `fp${i}`, + check: 'UndefinedObject', + file: `app/views/pages/page${i}.liquid`, + params: { variable: 'product' }, + }); + } + seedDiagnostics(store, events.map(e => ({ fp: e.fp, check_name: 'UndefinedObject', file: e.file }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'UndefinedObject', 'tpl1'); + expect(when.file_type).toBe('page'); + expect(when.param_equals).toEqual({ variable: 'product' }); + }); + + test('works with file_type only when no params in events', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'app/views/partials/a.liquid' }, + { fp: 'fp2', file: 'app/views/partials/b.liquid' }, + { fp: 'fp3', file: 'app/views/partials/c.liquid' }, + { fp: 'fp4', file: 'app/views/partials/d.liquid' }, + { fp: 'fp5', file: 'app/views/partials/e.liquid' }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.file_type).toBe('partial'); + expect(when.param_equals).toBeUndefined(); + expect(when.param_startsWith).toBeUndefined(); + expect(when.param_contains).toBeUndefined(); + }); + + test('respects minSamples for param analysis', () => { + const events = [ + { fp: 'fp0', check: 'TestCheck', params: { key: 'same' } }, + { fp: 'fp1', check: 'TestCheck', params: { key: 'same' } }, + { fp: 'fp2', check: 'TestCheck', params: { key: 'same' } }, + ]; + seedDiagnostics(store, events.map(e => ({ fp: e.fp }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1', { minSamples: 5 }); + expect(when.param_equals).toBeUndefined(); + }); + + test('ignores suppressed diagnostics for file_type', () => { + seedDiagnostics(store, [ + { fp: 'fp1', file: 'app/views/pages/a.liquid', suppressed: 0 }, + { fp: 'fp2', file: 'app/views/pages/b.liquid', suppressed: 0 }, + { fp: 'fp3', file: 'app/views/pages/c.liquid', suppressed: 0 }, + { fp: 'fp4', file: 'app/views/pages/d.liquid', suppressed: 0 }, + { fp: 'fp5', file: 'app/views/pages/e.liquid', suppressed: 0 }, + { fp: 'fp6', file: 'app/lib/commands/x.liquid', suppressed: 1 }, + { fp: 'fp7', file: 'app/lib/commands/y.liquid', suppressed: 1 }, + { fp: 'fp8', file: 'app/lib/commands/z.liquid', suppressed: 1 }, + ]); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.file_type).toBe('page'); + }); + + test('prefers param_equals over param_startsWith', () => { + const events = []; + for (let i = 0; i < 10; i++) { + events.push({ fp: `fp${i}`, check: 'TestCheck', params: { key: 'exactly_the_same' } }); + } + seedDiagnostics(store, events.map(e => ({ fp: e.fp }))); + seedEvents(store, events); + + const when = synthesizeGuardPredicate(store, 'TestCheck', 'tpl1'); + expect(when.param_equals).toEqual({ key: 'exactly_the_same' }); + expect(when.param_startsWith).toBeUndefined(); + expect(when.param_contains).toBeUndefined(); + }); +}); + +describe('generateRuleTemplate with guards', () => { + const baseSuggestion = { + check: 'UnknownFilter', + template_fp: 'abcdef1234567890', + resolution_rate: 0.85, + total_outcomes: 20, + sample_file: 'app/views/partials/test.liquid', + }; + + test('renders TODO when no guards', () => { + const template = generateRuleTemplate(baseSuggestion); + expect(template).toContain('TODO: Add guard predicate'); + expect(template).toContain('return true;'); + }); + + test('renders file_type guard', () => { + const template = generateRuleTemplate(baseSuggestion, { file_type: 'page' }); + expect(template).toContain("diag.file?.includes(\"/pages/\")"); + expect(template).not.toContain('TODO: Add guard predicate'); + }); + + test('renders param_equals guard', () => { + const template = generateRuleTemplate(baseSuggestion, { param_equals: { filter: 'asset_url' } }); + expect(template).toContain("diag.params?.filter === \"asset_url\""); + }); + + test('renders param_startsWith guard', () => { + const template = generateRuleTemplate(baseSuggestion, { param_startsWith: { partial: 'modules/' } }); + expect(template).toContain("diag.params?.partial?.startsWith(\"modules/\")"); + }); + + test('renders param_contains guard', () => { + const template = generateRuleTemplate(baseSuggestion, { param_contains: { filter: 'img_url' } }); + expect(template).toContain("diag.params?.filter?.includes(\"img_url\")"); + }); + + test('renders combined guards with &&', () => { + const guards = { + file_type: 'partial', + param_equals: { variable: 'product' }, + }; + const template = generateRuleTemplate(baseSuggestion, guards); + expect(template).toContain('&&'); + expect(template).toContain("diag.params?.variable === \"product\""); + expect(template).toContain("diag.file?.includes(\"/partials/\")"); + }); + + test('preserves existing template fields', () => { + const template = generateRuleTemplate(baseSuggestion, { file_type: 'page' }); + expect(template).toContain("id: 'UnknownFilter.case_abcdef12'"); + expect(template).toContain("check: 'UnknownFilter'"); + expect(template).toContain('confidence: 0.85'); + expect(template).toContain('85% across 20 outcomes'); + }); +}); diff --git a/tests/unit/lsp-stale-diagnostics.test.js b/tests/unit/lsp-stale-diagnostics.test.js index 4b75a44..405d730 100644 --- a/tests/unit/lsp-stale-diagnostics.test.js +++ b/tests/unit/lsp-stale-diagnostics.test.js @@ -88,20 +88,19 @@ describe('awaitDiagnostics barrier + settle pattern', () => { client.stop(); }); - it('post-barrier diagnostics replace pre-barrier ones', async () => { + it('later diagnostics replace earlier ones via settle window', async () => { const { client, send, captured } = startClient(); const uri = 'file:///test/app/stale.liquid'; const promise = client.awaitDiagnostics(uri, 'line1\nline2\n', 2000); const hoverReq = captured.find(m => m.method === 'textDocument/hover'); - // Pre-barrier diagnostics — stored but settle not started yet - send(diagNotification(uri, [diag(9, 'PreBarrierCheck', 'from old analysis')])); + // Early diagnostics accepted, settle timer starts + send(diagNotification(uri, [diag(9, 'EarlyCheck', 'from old analysis')])); - // Barrier response — if we have diags, settle timer starts send(hoverResponse(hoverReq.id)); - // Fresh diagnostics arrive AFTER barrier — replace pre-barrier ones, reset settle + // Later diagnostics replace earlier ones, settle timer resets send(diagNotification(uri, [diag(0, 'FreshCheck', 'from new content')])); const result = await promise; @@ -110,18 +109,15 @@ describe('awaitDiagnostics barrier + settle pattern', () => { client.stop(); }); - it('handles pre-barrier + barrier + post-barrier in rapid sequence', async () => { + it('handles rapid sequence of diagnostics — settle picks latest', async () => { const { client, send, captured } = startClient(); const uri = 'file:///test/app/onechunk.liquid'; const promise = client.awaitDiagnostics(uri, 'a\nb\n', 2000); const hoverReq = captured.find(m => m.method === 'textDocument/hover'); - // Write all three messages rapidly — #drain processes them sequentially - // 1. pre-barrier diag → stored, settle deferred - // 2. hover response → barrier passes, settle starts - // 3. post-barrier diag → replaces pre-barrier, settle resets - send(diagNotification(uri, [diag(10, 'PreBarrierCheck')])); + // All three messages arrive rapidly — settle picks the last batch + send(diagNotification(uri, [diag(10, 'EarlyCheck')])); send(hoverResponse(hoverReq.id)); send(diagNotification(uri, [diag(0, 'FreshCheck')])); @@ -131,6 +127,25 @@ describe('awaitDiagnostics barrier + settle pattern', () => { client.stop(); }); + it('accepts diagnostics that arrive before barrier hover responds', async () => { + const { client, send, captured } = startClient(); + const uri = 'file:///test/app/fast-lsp.liquid'; + + const promise = client.awaitDiagnostics(uri, '{{ x | bad_filter }}\n', 2000); + const hoverReq = captured.find(m => m.method === 'textDocument/hover'); + + // LSP emits diagnostics BEFORE responding to hover (fast analysis) + send(diagNotification(uri, [diag(0, 'UnknownFilter', 'Unknown filter bad_filter')])); + + // Hover response arrives later + send(hoverResponse(hoverReq.id)); + + const result = await promise; + expect(result).toHaveLength(1); + expect(result[0].code).toBe('UnknownFilter'); + client.stop(); + }); + it('resolves with empty array on timeout (no diagnostics after barrier)', async () => { const { client, send, captured } = startClient(); const uri = 'file:///test/app/timeout.liquid'; @@ -156,18 +171,16 @@ describe('awaitDiagnostics barrier + settle pattern', () => { client.stop(); }); - it('accepts diagnostics after barrier timeout (barrier gate opens on timeout)', async () => { + it('accepts diagnostics even when barrier hover never responds', async () => { const { client, send } = startClient(); const uri = 'file:///test/app/late-barrier.liquid'; - // Use a longer main timeout so diagnostics can arrive after barrier timeout const promise = client.awaitDiagnostics(uri, 'content\n', 5000); - // Don't respond to barrier — it will time out after 3s (min of timeout, 3000) - // But diagnostics arrive after the barrier timeout + // Don't respond to barrier hover — diagnostics still accepted setTimeout(() => { send(diagNotification(uri, [diag(0, 'LateCheck')])); - }, 3100); + }, 100); const result = await promise; expect(result).toHaveLength(1); @@ -187,17 +200,14 @@ describe('awaitDiagnostics barrier + settle pattern', () => { client.stop(); }); - it('barrier gate opens on hover error response', async () => { + it('accepts diagnostics when hover responds with error', async () => { const { client, send, captured } = startClient(); const uri = 'file:///test/app/hover-error.liquid'; const promise = client.awaitDiagnostics(uri, 'content\n', 2000); const hoverReq = captured.find(m => m.method === 'textDocument/hover'); - // LSP responds with error (e.g., unsupported file type) send({ jsonrpc: '2.0', id: hoverReq.id, error: { code: -32601, message: 'not supported' } }); - - // Fresh diagnostics should still be accepted send(diagNotification(uri, [diag(0, 'FreshAfterError')])); const result = await promise; @@ -219,19 +229,18 @@ describe('awaitDiagnostics barrier + settle pattern', () => { expect(r1).toHaveLength(1); expect(r1[0].code).toBe('V1Check'); - // Second call — new barrier + // Second call — settle window picks the latest batch captured.length = 0; const p2 = client.awaitDiagnostics(uri, 'v2\n', 2000); const hover2 = captured.find(m => m.method === 'textDocument/hover'); expect(hover2).toBeDefined(); - // Pre-barrier diagnostics from v1 analysis still arriving - send(diagNotification(uri, [diag(0, 'PreBarrierV1')])); + // Stale v1 diagnostics arrive first + send(diagNotification(uri, [diag(0, 'StaleV1')])); - // Barrier passes send(hoverResponse(hover2.id)); - // Fresh v2 diagnostics replace pre-barrier ones + // Fresh v2 diagnostics replace stale ones via settle window send(diagNotification(uri, [diag(0, 'V2Check')])); const r2 = await p2; diff --git a/tests/unit/promoted-rules.test.js b/tests/unit/promoted-rules.test.js index 1b4ea09..a62bad2 100644 --- a/tests/unit/promoted-rules.test.js +++ b/tests/unit/promoted-rules.test.js @@ -441,3 +441,448 @@ describe('promoted-rules: glob patterns', () => { expect(compiled[0].when({ file: 'app/views/pages/blog/index.liquid' })).toBe(false); }); }); + +// ── Graph-aware guards ────────────────────────────────────────────────────── + +function mockGraph(nodes = {}, edges = {}) { + return { + referencedBy(filePath) { + return edges[filePath] ?? []; + }, + hasNode(filePath) { + return filePath in nodes; + }, + nodeByPath(filePath) { + return nodes[filePath] ?? null; + }, + }; +} + +describe('promoted-rules: graph-aware guards', () => { + beforeEach(setup); + afterEach(teardown); + + it('has_callers: true matches when file has callers', () => { + writeRules([{ + id: 'test_has_callers_true', + check: 'TestCheck', + when: { has_callers: true }, + apply: { hint_md: 'Has callers.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/card.liquid': { type: 'partial', key: 'card' } }, + { 'app/views/partials/card.liquid': ['app/views/pages/index.liquid'] }, + ); + + expect(guard({ file: 'app/views/partials/card.liquid' }, { graph })).toBe(true); + }); + + it('has_callers: true rejects when file has no callers', () => { + writeRules([{ + id: 'test_has_callers_true_no_refs', + check: 'TestCheck', + when: { has_callers: true }, + apply: { hint_md: 'Has callers.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/orphan.liquid': { type: 'partial', key: 'orphan' } }, + { 'app/views/partials/orphan.liquid': [] }, + ); + + expect(guard({ file: 'app/views/partials/orphan.liquid' }, { graph })).toBe(false); + }); + + it('has_callers: false matches when file has no callers', () => { + writeRules([{ + id: 'test_has_callers_false', + check: 'TestCheck', + when: { has_callers: false }, + apply: { hint_md: 'No callers.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/orphan.liquid': { type: 'partial', key: 'orphan' } }, + { 'app/views/partials/orphan.liquid': [] }, + ); + + expect(guard({ file: 'app/views/partials/orphan.liquid' }, { graph })).toBe(true); + }); + + it('caller_count_gte matches when callers >= threshold', () => { + writeRules([{ + id: 'test_caller_count', + check: 'TestCheck', + when: { caller_count_gte: 3 }, + apply: { hint_md: 'Many callers.', confidence: 0.7 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/header.liquid': { type: 'partial', key: 'header' } }, + { 'app/views/partials/header.liquid': ['page1.liquid', 'page2.liquid', 'page3.liquid'] }, + ); + + expect(guard({ file: 'app/views/partials/header.liquid' }, { graph })).toBe(true); + }); + + it('caller_count_gte rejects when callers < threshold', () => { + writeRules([{ + id: 'test_caller_count_below', + check: 'TestCheck', + when: { caller_count_gte: 3 }, + apply: { hint_md: 'Many callers.', confidence: 0.7 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/header.liquid': { type: 'partial', key: 'header' } }, + { 'app/views/partials/header.liquid': ['page1.liquid', 'page2.liquid'] }, + ); + + expect(guard({ file: 'app/views/partials/header.liquid' }, { graph })).toBe(false); + }); + + it('has_params: true matches when file has doc params', () => { + writeRules([{ + id: 'test_has_params_true', + check: 'TestCheck', + when: { has_params: true }, + apply: { hint_md: 'Documented partial.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph({ + 'app/views/partials/card.liquid': { type: 'partial', key: 'card', params: ['title', 'image'] }, + }); + + expect(guard({ file: 'app/views/partials/card.liquid' }, { graph })).toBe(true); + }); + + it('has_params: false matches when file has no doc params', () => { + writeRules([{ + id: 'test_has_params_false', + check: 'TestCheck', + when: { has_params: false }, + apply: { hint_md: 'Undocumented partial.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph({ + 'app/views/partials/card.liquid': { type: 'partial', key: 'card', params: [] }, + }); + + expect(guard({ file: 'app/views/partials/card.liquid' }, { graph })).toBe(true); + }); + + it('has_params: true rejects when file has no params', () => { + writeRules([{ + id: 'test_has_params_true_no_params', + check: 'TestCheck', + when: { has_params: true }, + apply: { hint_md: 'Documented.', confidence: 0.6 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph({ + 'app/views/partials/card.liquid': { type: 'partial', key: 'card', params: [] }, + }); + + expect(guard({ file: 'app/views/partials/card.liquid' }, { graph })).toBe(false); + }); + + it('is_orphan: true matches orphan files', () => { + writeRules([{ + id: 'test_is_orphan_true', + check: 'TestCheck', + when: { is_orphan: true }, + apply: { hint_md: 'Orphan file.', confidence: 0.5 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/dead.liquid': { type: 'partial', key: 'dead' } }, + { 'app/views/partials/dead.liquid': [] }, + ); + + expect(guard({ file: 'app/views/partials/dead.liquid' }, { graph })).toBe(true); + }); + + it('is_orphan: false matches non-orphan files', () => { + writeRules([{ + id: 'test_is_orphan_false', + check: 'TestCheck', + when: { is_orphan: false }, + apply: { hint_md: 'Not orphan.', confidence: 0.5 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/used.liquid': { type: 'partial', key: 'used' } }, + { 'app/views/partials/used.liquid': ['page.liquid'] }, + ); + + expect(guard({ file: 'app/views/partials/used.liquid' }, { graph })).toBe(true); + }); + + it('is_orphan: true rejects when file has callers', () => { + writeRules([{ + id: 'test_is_orphan_true_has_callers', + check: 'TestCheck', + when: { is_orphan: true }, + apply: { hint_md: 'Orphan.', confidence: 0.5 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/used.liquid': { type: 'partial', key: 'used' } }, + { 'app/views/partials/used.liquid': ['caller.liquid'] }, + ); + + expect(guard({ file: 'app/views/partials/used.liquid' }, { graph })).toBe(false); + }); + + it('graph guards degrade gracefully when no graph provided', () => { + writeRules([{ + id: 'test_no_graph', + check: 'TestCheck', + when: { has_callers: true }, + apply: { hint_md: 'Needs callers.', confidence: 0.5 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + + expect(guard({ file: 'app/views/partials/card.liquid' }, {})).toBe(false); + expect(guard({ file: 'app/views/partials/card.liquid' }, null)).toBe(false); + expect(guard({ file: 'app/views/partials/card.liquid' })).toBe(false); + }); + + it('graph guards degrade gracefully when no diag.file', () => { + writeRules([{ + id: 'test_no_file', + check: 'TestCheck', + when: { is_orphan: true }, + apply: { hint_md: 'Orphan.', confidence: 0.5 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph({ 'app/views/partials/x.liquid': { type: 'partial' } }); + + expect(guard({}, { graph })).toBe(false); + expect(guard({ file: null }, { graph })).toBe(false); + expect(guard({ file: undefined }, { graph })).toBe(false); + }); + + it('combines graph guards with param guards (AND semantics)', () => { + writeRules([{ + id: 'test_combined_graph_param', + check: 'MissingPartial', + when: { + param_startsWith: { name: 'modules/' }, + has_callers: true, + is_orphan: false, + }, + apply: { hint_md: 'Module partial with callers.', confidence: 0.8 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/mod.liquid': { type: 'partial', key: 'mod' } }, + { 'app/views/partials/mod.liquid': ['page.liquid'] }, + ); + + expect(guard( + { params: { name: 'modules/user/form' }, file: 'app/views/partials/mod.liquid' }, + { graph }, + )).toBe(true); + + expect(guard( + { params: { name: 'blog/form' }, file: 'app/views/partials/mod.liquid' }, + { graph }, + )).toBe(false); + + expect(guard( + { params: { name: 'modules/user/form' }, file: 'app/views/partials/mod.liquid' }, + {}, + )).toBe(false); + }); + + it('combines file_type + graph guards', () => { + writeRules([{ + id: 'test_filetype_graph', + check: 'TestCheck', + when: { + file_type: 'partial', + caller_count_gte: 2, + has_params: true, + }, + apply: { hint_md: 'Popular documented partial.', confidence: 0.9 }, + }]); + const compiled = loadPromotedRules(tmpDir); + const guard = compiled[0].when; + const graph = mockGraph( + { 'app/views/partials/card.liquid': { type: 'partial', key: 'card', params: ['title'] } }, + { 'app/views/partials/card.liquid': ['page1.liquid', 'page2.liquid'] }, + ); + + expect(guard( + { file: 'app/views/partials/card.liquid' }, + { graph }, + )).toBe(true); + + const graphFewCallers = mockGraph( + { 'app/views/partials/card.liquid': { type: 'partial', key: 'card', params: ['title'] } }, + { 'app/views/partials/card.liquid': ['page1.liquid'] }, + ); + expect(guard( + { file: 'app/views/partials/card.liquid' }, + { graph: graphFewCallers }, + )).toBe(false); + }); + + it('engine integration: graph-aware rule fires via runRules', () => { + writeRules([{ + id: 'TestCheck.graph_rule', + check: 'TestCheck', + priority: 55, + when: { has_callers: true, caller_count_gte: 1 }, + apply: { hint_md: 'File has callers.', confidence: 0.7 }, + }]); + loadPromotedRules(tmpDir); + + const diag = { check: 'TestCheck', file: 'app/views/partials/card.liquid' }; + const graph = mockGraph( + { 'app/views/partials/card.liquid': { type: 'partial', key: 'card' } }, + { 'app/views/partials/card.liquid': ['page.liquid'] }, + ); + const result = runRules(diag, { graph }); + + expect(result).not.toBeNull(); + expect(result.rule_id).toBe('TestCheck.graph_rule'); + }); + + it('engine integration: graph-aware rule skipped when guard fails', () => { + writeRules([{ + id: 'TestCheck.graph_only_callers', + check: 'TestCheck', + priority: 55, + when: { caller_count_gte: 5 }, + apply: { hint_md: 'Very popular.', confidence: 0.9 }, + }]); + loadPromotedRules(tmpDir); + + const diag = { check: 'TestCheck', file: 'app/views/partials/card.liquid' }; + const graph = mockGraph( + { 'app/views/partials/card.liquid': { type: 'partial', key: 'card' } }, + { 'app/views/partials/card.liquid': ['page.liquid', 'page2.liquid'] }, + ); + const result = runRules(diag, { graph }); + + expect(result).toBeNull(); + }); +}); + +// ── Query helpers ─────────────────────────────────────────────────────────── + +import { callerCount, isOrphan, hasDocParams, classifyFileType } from '../../src/core/rules/queries.js'; + +describe('queries: callerCount', () => { + it('returns caller count from graph', () => { + const graph = mockGraph({}, { 'a.liquid': ['b.liquid', 'c.liquid'] }); + expect(callerCount(graph, 'a.liquid')).toBe(2); + }); + + it('returns 0 for file with no callers', () => { + const graph = mockGraph({}, { 'a.liquid': [] }); + expect(callerCount(graph, 'a.liquid')).toBe(0); + }); + + it('returns 0 when graph is null', () => { + expect(callerCount(null, 'a.liquid')).toBe(0); + }); + + it('returns 0 when filePath is null', () => { + const graph = mockGraph({}, {}); + expect(callerCount(graph, null)).toBe(0); + }); +}); + +describe('queries: isOrphan', () => { + it('returns true for file in graph with no callers', () => { + const graph = mockGraph( + { 'a.liquid': { type: 'partial' } }, + { 'a.liquid': [] }, + ); + expect(isOrphan(graph, 'a.liquid')).toBe(true); + }); + + it('returns false for file with callers', () => { + const graph = mockGraph( + { 'a.liquid': { type: 'partial' } }, + { 'a.liquid': ['b.liquid'] }, + ); + expect(isOrphan(graph, 'a.liquid')).toBe(false); + }); + + it('returns false for file not in graph', () => { + const graph = mockGraph({}, {}); + expect(isOrphan(graph, 'unknown.liquid')).toBe(false); + }); + + it('returns false when graph is null', () => { + expect(isOrphan(null, 'a.liquid')).toBe(false); + }); +}); + +describe('queries: hasDocParams', () => { + it('returns true when node has params array with entries', () => { + const graph = mockGraph({ 'a.liquid': { params: ['title', 'image'] } }); + expect(hasDocParams(graph, 'a.liquid')).toBe(true); + }); + + it('returns false when node has empty params array', () => { + const graph = mockGraph({ 'a.liquid': { params: [] } }); + expect(hasDocParams(graph, 'a.liquid')).toBe(false); + }); + + it('returns false when node has no params field', () => { + const graph = mockGraph({ 'a.liquid': { type: 'partial' } }); + expect(hasDocParams(graph, 'a.liquid')).toBe(false); + }); + + it('returns false when node not found', () => { + const graph = mockGraph({}); + expect(hasDocParams(graph, 'unknown.liquid')).toBe(false); + }); + + it('returns false when graph is null', () => { + expect(hasDocParams(null, 'a.liquid')).toBe(false); + }); +}); + +describe('queries: classifyFileType', () => { + const cases = [ + ['app/views/pages/index.html.liquid', 'page'], + ['app/views/partials/card.liquid', 'partial'], + ['app/views/layouts/main.liquid', 'layout'], + ['app/lib/commands/blog/create.liquid', 'command'], + ['app/lib/queries/blog/search.liquid', 'query'], + ['app/graphql/blog/create.graphql', 'graphql'], + ['app/schema/blog.yml', 'schema'], + ['modules/user/form.liquid', 'module'], + ['some/other/path.liquid', 'unknown'], + [null, 'unknown'], + [undefined, 'unknown'], + ['', 'unknown'], + ]; + + for (const [input, expected] of cases) { + it(`classifies ${JSON.stringify(input)} as ${expected}`, () => { + expect(classifyFileType(input)).toBe(expected); + }); + } +}); diff --git a/tests/unit/translation-validator.test.js b/tests/unit/translation-validator.test.js new file mode 100644 index 0000000..18a524f --- /dev/null +++ b/tests/unit/translation-validator.test.js @@ -0,0 +1,114 @@ +import { describe, it, expect } from 'bun:test'; +import { validateTranslationYaml } from '../../src/core/translation-validator.js'; + +function validate(content, filePath = 'app/translations/en.yml') { + return validateTranslationYaml(content, filePath); +} + +describe('translation-validator: missing top-level locale key', () => { + it('errors when the tree has no locale wrapper', () => { + const yaml = `app: + contact_form: + title: "Contact us" + success: "Thanks" +`; + const { errors } = validate(yaml); + expect(errors.some(e => e.check === 'pos-supervisor:TranslationMissingLocaleKey')).toBe(true); + expect(errors[0].message).toMatch(/en:/); + }); + + it('suggests the filename-based locale when available', () => { + const { errors } = validate('app:\n title: x\n', 'app/translations/de.yml'); + expect(errors[0].message).toMatch(/de:/); + }); + + it('falls back to en when filename is not a locale', () => { + const { errors } = validate('app:\n title: x\n', 'app/translations/strings.yml'); + expect(errors[0].message).toMatch(/en:/); + }); + + it('rejects multiple non-locale top-level keys', () => { + const yaml = `app: + title: x +ecommerce: + cart: y +`; + const { errors } = validate(yaml); + expect(errors).toHaveLength(1); + expect(errors[0].check).toBe('pos-supervisor:TranslationMissingLocaleKey'); + }); +}); + +describe('translation-validator: valid locale wrappers', () => { + it('passes a correctly wrapped file', () => { + const yaml = `en: + app: + contact_form: + title: "Contact" +`; + const { errors, warnings } = validate(yaml); + expect(errors).toHaveLength(0); + expect(warnings).toHaveLength(0); + }); + + it('accepts two-letter locale with region (pt-BR)', () => { + const { errors } = validate('pt-BR:\n app:\n title: "x"\n', 'app/translations/pt-BR.yml'); + expect(errors).toHaveLength(0); + }); + + it('accepts a multi-locale file', () => { + const yaml = `en: + app: + title: "Contact" +de: + app: + title: "Kontakt" +`; + const { errors, warnings } = validate(yaml); + expect(errors).toHaveLength(0); + expect(warnings).toHaveLength(0); + }); +}); + +describe('translation-validator: mixed top-level keys', () => { + it('warns per stray non-locale key when at least one locale is present', () => { + const yaml = `en: + app: + title: "x" +app: + title: "y" +`; + const { errors, warnings } = validate(yaml); + expect(errors).toHaveLength(0); + expect(warnings.some(w => w.check === 'pos-supervisor:TranslationStrayTopKey' && w.message.includes('`app`'))).toBe(true); + }); +}); + +describe('translation-validator: edge cases', () => { + it('returns nothing on empty content', () => { + const { errors, warnings } = validate(''); + expect(errors).toHaveLength(0); + expect(warnings).toHaveLength(0); + }); + + it('returns nothing on comment-only content', () => { + const { errors, warnings } = validate('# just a comment\n'); + expect(errors).toHaveLength(0); + expect(warnings).toHaveLength(0); + }); + + it('errors on invalid YAML syntax', () => { + const { errors } = validate('en:\n app:\n title: "unterminated'); + expect(errors.some(e => e.check === 'pos-supervisor:TranslationYAML')).toBe(true); + }); + + it('errors when root is an array', () => { + const { errors } = validate('- one\n- two\n'); + expect(errors.some(e => e.check === 'pos-supervisor:TranslationStructure')).toBe(true); + }); + + it('errors when root is a scalar string', () => { + const { errors } = validate('just a string\n'); + expect(errors.some(e => e.check === 'pos-supervisor:TranslationStructure')).toBe(true); + }); +}); From 8013b7ddc64cb010c6d5083e83598d2afef5b18f Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Tue, 21 Apr 2026 18:29:20 +0200 Subject: [PATCH 13/20] Translations: file first in fix_order + orphan detection suppresion --- src/core/dependency-graph.js | 4 + src/tools/analyze-project.js | 151 ++++++++++++- tests/unit/analyze-project.test.js | 269 +++++++++++++++++++++++ tests/unit/dependency-graph.test.js | 11 + tests/unit/translation-validator.test.js | 11 + 5 files changed, 441 insertions(+), 5 deletions(-) create mode 100644 tests/unit/analyze-project.test.js diff --git a/src/core/dependency-graph.js b/src/core/dependency-graph.js index fc3ec44..5384cb4 100644 --- a/src/core/dependency-graph.js +++ b/src/core/dependency-graph.js @@ -305,6 +305,10 @@ export function detectOrphanedFiles(graph, projectMap) { // GraphQL files: flagged elsewhere by the integrity check for orphaned ops. if (path.endsWith('.graphql')) continue; + // Translation files: structural errors are surfaced by translation-validator; + // they are never rendered by liquid files so they have no referenced_by edges. + if (path.startsWith('app/translations/')) continue; + // Anything outside app/ is assumed external (module fallback path) and skipped. if (!path.startsWith('app/')) continue; diff --git a/src/tools/analyze-project.js b/src/tools/analyze-project.js index 8c37c95..93b4a84 100644 --- a/src/tools/analyze-project.js +++ b/src/tools/analyze-project.js @@ -3,6 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'; import { join } from 'node:path'; import { createCheckRunner } from '../core/check-runner.js'; import { validateSchema } from '../core/schema-validator.js'; +import { validateTranslationYaml } from '../core/translation-validator.js'; import { toUri, sanitizePath } from '../core/utils.js'; import { getProjectMap } from './project-map.js'; import { ToolError } from '../core/tool-error.js'; @@ -44,8 +45,11 @@ export const analyzeProjectTool = { // If no files specified, use the fact graph's indexed file list instead of // re-walking app/ (eliminates the parallel-walk class of bugs). + // Also include translation files explicitly so they're part of the primary analysis. if (!files || !Array.isArray(files) || files.length === 0) { - files = factGraph.allCheckableFiles(); + const checkableFiles = factGraph.allCheckableFiles(); + const translationFiles = getTranslationFilePaths(projectMap); + files = [...checkableFiles, ...translationFiles]; if (files.length === 0) { throw new ToolError('No .liquid or .graphql files found in app/', { status: 404 }); } @@ -164,6 +168,30 @@ export const analyzeProjectTool = { } } catch { /* schema directory not found — skip */ } + // Translation validation — catch structural invariant violations (e.g. missing + // top-level locale key, stray non-locale top-level keys) that pos-cli check + // does not report as errors on the .yml file itself. Without this step, a + // broken translation file (e.g. `enff:` instead of `en:`) has 0 pos-cli errors + // and never enters fix_order, even though it is the root cause of + // TranslationKeyExists errors on every liquid file that uses translation keys. + for (const tranPath of getTranslationFilePaths(projectMap)) { + try { + const content = await readFile(join(ctx.directory, tranPath), 'utf8'); + const transResult = validateTranslationYaml(content, tranPath); + const errorCount = transResult.errors.length; + const warningCount = transResult.warnings.length; + const hasRelevant = errorCount > 0 || (minRank <= 2 && warningCount > 0); + if (!hasRelevant) continue; + const existing = fileResults.find(f => f.path === tranPath); + if (existing) { + existing.errors += errorCount; + existing.warnings += warningCount; + } else { + fileResults.push({ path: tranPath, errors: errorCount, warnings: warningCount }); + } + } catch { /* translation file read/parse failure — skip */ } + } + // Build dependency graph. // // The LSP's appGraph/* methods return empty arrays for files it has not @@ -178,6 +206,7 @@ export const analyzeProjectTool = { const lspOverlay = {}; if (ctx.lsp?.initialized) { for (const filePath of files) { + if (filePath.endsWith('.yml') || filePath.endsWith('.yaml')) continue; const absPath = absPaths[filePath]; const uri = toUri(absPath); try { @@ -215,18 +244,44 @@ export const analyzeProjectTool = { integrity = integrity.filter(i => (SEV_RANK[i.severity] ?? 1) >= minRank); } + // Inject translation dependency edges into dependencyGraph so buildFixOrder + // can place the translation file before the liquid files it breaks. + // filesAffectedByTranslationFile relies on translation_keys in projectMap + // which the scanner doesn't populate — using allResults.errors directly + // gives us the ground truth: every file with a TranslationKeyExists error + // implicitly depends on the broken translation file. + const tranPrefix = ctx.directory.endsWith('/') ? ctx.directory : ctx.directory + '/'; + for (const tranPath of getTranslationFilePaths(projectMap)) { + if (!fileResults.some(f => f.path === tranPath && f.errors > 0)) continue; + for (const d of allResults.errors) { + if (d.check !== 'TranslationKeyExists') continue; + const rel = d._filePath?.startsWith(tranPrefix) + ? d._filePath.slice(tranPrefix.length) + : d._filePath; + if (!rel || rel === tranPath) continue; + if (!dependencyGraph[rel]) dependencyGraph[rel] = { depends_on: [], referenced_by: [] }; + if (!dependencyGraph[rel].depends_on.includes(tranPath)) { + dependencyGraph[rel].depends_on.push(tranPath); + } + if (!dependencyGraph[tranPath]) dependencyGraph[tranPath] = { depends_on: [], referenced_by: [] }; + if (!dependencyGraph[tranPath].referenced_by.includes(rel)) { + dependencyGraph[tranPath].referenced_by.push(rel); + } + } + } + const lintErrors = fileResults.reduce((s, f) => s + f.errors, 0); const lintWarnings = fileResults.reduce((s, f) => s + f.warnings, 0); const integrityErrors = integrity.filter(i => i.severity === 'error').length; const integrityWarnings = integrity.filter(i => i.severity === 'warning').length; - const fix_order = buildFixOrder(fileResults, dependencyGraph, ctx.directory); + const fix_order = buildFixOrder(fileResults, dependencyGraph, ctx.directory, projectMap); const totalErrors = lintErrors + integrityErrors; const totalWarnings = lintWarnings + integrityWarnings; // ── blocking_files: files with errors that must be fixed ──────────── - const blockingFiles = computeBlockingFiles(fileResults, integrity, allResults); + const blockingFiles = computeBlockingFiles(fileResults, integrity, allResults, ctx.directory, projectMap); // ── diff_from_last_run: compare against previous analysis ────────── const prefix = ctx.directory.endsWith('/') ? ctx.directory : ctx.directory + '/'; @@ -279,12 +334,16 @@ export const analyzeProjectTool = { * If A renders/calls B and both have errors, B should be fixed first — * fixing B may eliminate cascade errors in A. * + * Translation files are handled specially: they have implicit dependents + * (all files that use translation keys). These are computed at analyze time. + * * @param {{ path: string, errors: number, warnings: number }[]} fileResults * @param {Record} dependencyGraph * @param {string} projectDir - absolute project root + * @param {object} projectMap - project indexing result (for translation file handling) * @returns {{ path: string, errors: number, warnings: number, reason: string, dependents_with_errors: number }[]} */ -export function buildFixOrder(fileResults, dependencyGraph, projectDir) { +export function buildFixOrder(fileResults, dependencyGraph, projectDir, projectMap) { if (fileResults.length === 0) return []; const errorPaths = new Set(fileResults.map(f => f.path)); @@ -316,6 +375,20 @@ export function buildFixOrder(fileResults, dependencyGraph, projectDir) { } } + // Handle translation file implicit dependents: files that use translation keys + // depend on translation files, so if a translation file has errors, all its + // dependents should be fixed after it. + for (const tranFile of fileResults.filter(f => f.path.startsWith('app/translations/'))) { + const affectedFiles = filesAffectedByTranslationFile(tranFile.path, projectMap); + for (const affectedPath of affectedFiles) { + if (errorPaths.has(affectedPath)) { + // affectedPath depends on tranFile + deps[affectedPath].add(tranFile.path); + dependents[tranFile.path].add(affectedPath); + } + } + } + // Kahn's algorithm — nodes with in-degree 0 (no unresolved deps) go first. const inDegree = {}; for (const f of fileResults) inDegree[f.path] = deps[f.path].size; @@ -496,8 +569,10 @@ function matchesFile(diagnostic, absPath, relPath) { * @param {Array} fileResults - per-file { path, errors, warnings } * @param {Array} integrity - integrity issues with { severity, source, type } * @param {{ errors: Array }} [allResults] - full diagnostic results for check name extraction + * @param {string} [projectDir] - absolute project root, needed for translation file path normalisation + * @param {object} [projectMap] - project indexing result, needed to discover translation files */ -export function computeBlockingFiles(fileResults, integrity, allResults) { +export function computeBlockingFiles(fileResults, integrity, allResults, projectDir, projectMap) { const blockMap = new Map(); for (const f of fileResults) { @@ -517,6 +592,28 @@ export function computeBlockingFiles(fileResults, integrity, allResults) { } } + // Explicitly ensure translation file errors reach blocking_files even when the + // caller provided an explicit files list that excluded translation files. + // (When files come from the default discovery path, translation files are already + // in fileResults via Change 1a — this handles the explicit-files-list case.) + if (projectDir && projectMap && allResults?.errors) { + const prefix = projectDir.endsWith('/') ? projectDir : projectDir + '/'; + for (const tranPath of getTranslationFilePaths(projectMap)) { + if (blockMap.has(tranPath)) continue; + const errors = allResults.errors.filter(d => { + if (!d._filePath) return false; + const rel = d._filePath.startsWith(prefix) + ? d._filePath.slice(prefix.length) + : d._filePath; + return rel === tranPath; + }); + if (errors.length > 0) { + const checks = new Set(errors.map(e => e.check).filter(Boolean)); + blockMap.set(tranPath, { path: tranPath, lint_errors: errors.length, integrity_errors: 0, checks }); + } + } + } + for (const issue of integrity) { if (issue.severity !== 'error' || !issue.source) continue; const existing = blockMap.get(issue.source); @@ -590,3 +687,47 @@ export function computeDiffFromLastRun(session, currentSnapshot, totalErrors, to warning_delta: totalWarnings - (prev.total_warnings ?? 0), }; } + +/** + * Get the list of translation file paths from the project map. + * @param {object} projectMap - project indexing result + * @returns {string[]} relative paths like 'app/translations/en.yml' + */ +export function getTranslationFilePaths(projectMap) { + return Object.keys(projectMap.translations || {}).map( + locale => `app/translations/${locale}.yml` + ); +} + +/** + * Find all .liquid files that would be affected if a translation file has errors. + * Translation file errors (e.g., missing locale key, mismatched keys across locales) + * cause TranslationKeyExists failures on any file that references keys from that locale. + * + * @param {string} translationFilePath - e.g., 'app/translations/en.yml' + * @param {object} projectMap - project indexing result + * @returns {Set} relative paths of files that depend on this translation file + */ +export function filesAffectedByTranslationFile(translationFilePath, projectMap) { + const affected = new Set(); + const locale = translationFilePath.match(/\/(\w+)\.yml$/)?.[1]; + if (!locale) return affected; + + // Collect all files that use translation keys — these depend on the translation file + const allFiles = [ + ...Object.values(projectMap.pages || {}), + ...Object.values(projectMap.partials || {}), + ...Object.values(projectMap.commands || {}), + ...Object.values(projectMap.queries || {}), + ]; + + for (const file of allFiles) { + // If file has any translation key references, it depends on the translation file + if (file.translation_keys && file.translation_keys.length > 0) { + affected.add(file.path); + } + } + + return affected; +} + diff --git a/tests/unit/analyze-project.test.js b/tests/unit/analyze-project.test.js new file mode 100644 index 0000000..d775048 --- /dev/null +++ b/tests/unit/analyze-project.test.js @@ -0,0 +1,269 @@ +import { describe, it, expect } from 'bun:test'; +import { + getTranslationFilePaths, + filesAffectedByTranslationFile, + buildFixOrder, + computeBlockingFiles, +} from '../../src/tools/analyze-project.js'; + +const DIR = '/project'; + +// --------------------------------------------------------------------------- +// getTranslationFilePaths +// --------------------------------------------------------------------------- + +describe('getTranslationFilePaths', () => { + it('returns empty array when no translations in projectMap', () => { + expect(getTranslationFilePaths({})).toEqual([]); + expect(getTranslationFilePaths({ translations: {} })).toEqual([]); + }); + + it('maps locale keys to app/translations/.yml paths', () => { + const projectMap = { translations: { en: {}, de: {}, fr: {} } }; + const result = getTranslationFilePaths(projectMap); + expect(result).toHaveLength(3); + expect(result).toContain('app/translations/en.yml'); + expect(result).toContain('app/translations/de.yml'); + expect(result).toContain('app/translations/fr.yml'); + }); + + it('handles single locale', () => { + const result = getTranslationFilePaths({ translations: { en: {} } }); + expect(result).toEqual(['app/translations/en.yml']); + }); +}); + +// --------------------------------------------------------------------------- +// filesAffectedByTranslationFile +// --------------------------------------------------------------------------- + +describe('filesAffectedByTranslationFile', () => { + it('returns empty set for unknown locale path', () => { + const result = filesAffectedByTranslationFile('app/translations/.yml', {}); + expect(result.size).toBe(0); + }); + + it('returns empty set when no files use translation keys', () => { + const projectMap = { + pages: { show: { path: 'app/views/pages/show.html.liquid', translation_keys: [] } }, + partials: {}, + }; + const result = filesAffectedByTranslationFile('app/translations/en.yml', projectMap); + expect(result.size).toBe(0); + }); + + it('includes files that have translation_keys', () => { + const projectMap = { + pages: { + show: { path: 'app/views/pages/show.html.liquid', translation_keys: ['app.hello'] }, + }, + partials: { + header: { path: 'app/views/partials/header.liquid', translation_keys: ['app.nav.home'] }, + footer: { path: 'app/views/partials/footer.liquid', translation_keys: [] }, + }, + commands: {}, + queries: {}, + }; + const result = filesAffectedByTranslationFile('app/translations/en.yml', projectMap); + expect(result.has('app/views/pages/show.html.liquid')).toBe(true); + expect(result.has('app/views/partials/header.liquid')).toBe(true); + expect(result.has('app/views/partials/footer.liquid')).toBe(false); + }); + + it('includes commands and queries that use translation keys', () => { + const projectMap = { + pages: {}, + partials: {}, + commands: { + 'app/lib/commands/create.liquid': { + path: 'app/lib/commands/create.liquid', + translation_keys: ['app.success'], + }, + }, + queries: { + 'app/lib/queries/search.liquid': { + path: 'app/lib/queries/search.liquid', + translation_keys: ['app.no_results'], + }, + }, + }; + const result = filesAffectedByTranslationFile('app/translations/en.yml', projectMap); + expect(result.has('app/lib/commands/create.liquid')).toBe(true); + expect(result.has('app/lib/queries/search.liquid')).toBe(true); + }); + + it('works for non-en locales', () => { + const projectMap = { + pages: { show: { path: 'app/views/pages/show.html.liquid', translation_keys: ['app.hello'] } }, + partials: {}, + commands: {}, + queries: {}, + }; + const result = filesAffectedByTranslationFile('app/translations/de.yml', projectMap); + expect(result.has('app/views/pages/show.html.liquid')).toBe(true); + }); +}); + +// --------------------------------------------------------------------------- +// buildFixOrder — translation file scenarios +// --------------------------------------------------------------------------- + +function file(path, errors = 1, warnings = 0) { + return { path, errors, warnings }; +} + +describe('buildFixOrder — translation files', () => { + it('includes translation file in fix_order output', () => { + const files = [ + file('app/translations/en.yml'), + file('app/views/pages/show.html.liquid'), + ]; + const projectMap = { + pages: { show: { path: 'app/views/pages/show.html.liquid', translation_keys: ['app.hello'] } }, + partials: {}, + commands: {}, + queries: {}, + }; + const result = buildFixOrder(files, {}, DIR, projectMap); + expect(result).toHaveLength(2); + expect(result.map(r => r.path)).toContain('app/translations/en.yml'); + }); + + it('places translation file before dependent liquid files (via translation_keys)', () => { + const files = [ + file('app/views/pages/show.html.liquid'), + file('app/translations/en.yml'), + ]; + const projectMap = { + pages: { show: { path: 'app/views/pages/show.html.liquid', translation_keys: ['app.hello'] } }, + partials: {}, + commands: {}, + queries: {}, + }; + const result = buildFixOrder(files, {}, DIR, projectMap); + const paths = result.map(r => r.path); + expect(paths.indexOf('app/translations/en.yml')) + .toBeLessThan(paths.indexOf('app/views/pages/show.html.liquid')); + }); + + it('places translation file first when dependency graph has injected TranslationKeyExists edges', () => { + // Simulates what analyze_project does: inject edges for files with + // TranslationKeyExists errors so buildFixOrder can place translation file first. + const files = [ + file('app/views/pages/show.html.liquid'), + file('app/translations/en.yml'), + ]; + const depGraph = { + 'app/views/pages/show.html.liquid': { + depends_on: ['app/translations/en.yml'], + referenced_by: [], + }, + 'app/translations/en.yml': { + depends_on: [], + referenced_by: ['app/views/pages/show.html.liquid'], + }, + }; + const result = buildFixOrder(files, depGraph, DIR, {}); + expect(result[0].path).toBe('app/translations/en.yml'); + expect(result[0].dependents_with_errors).toBe(1); + }); + + it('counts dependent files with errors in dependents_with_errors', () => { + const files = [ + file('app/translations/en.yml'), + file('app/views/pages/a.html.liquid'), + file('app/views/pages/b.html.liquid'), + ]; + const projectMap = { + pages: { + a: { path: 'app/views/pages/a.html.liquid', translation_keys: ['app.x'] }, + b: { path: 'app/views/pages/b.html.liquid', translation_keys: ['app.y'] }, + }, + partials: {}, + commands: {}, + queries: {}, + }; + const result = buildFixOrder(files, {}, DIR, projectMap); + const tran = result.find(r => r.path === 'app/translations/en.yml'); + expect(tran.dependents_with_errors).toBe(2); + expect(tran.reason).toMatch(/Fix first/); + }); + + it('does not include translation dependents without errors', () => { + // Only translation file has errors; pages have no errors → not in fileResults + const files = [file('app/translations/en.yml')]; + const projectMap = { + pages: { show: { path: 'app/views/pages/show.html.liquid', translation_keys: ['app.hello'] } }, + partials: {}, + commands: {}, + queries: {}, + }; + const result = buildFixOrder(files, {}, DIR, projectMap); + expect(result).toHaveLength(1); + const tran = result[0]; + expect(tran.dependents_with_errors).toBe(0); + expect(tran.reason).toBe('No cross-error dependencies'); + }); + + it('works when projectMap is undefined (backward compat)', () => { + const files = [file('app/a.liquid')]; + expect(() => buildFixOrder(files, {}, DIR, undefined)).not.toThrow(); + const result = buildFixOrder(files, {}, DIR, undefined); + expect(result).toHaveLength(1); + }); +}); + +// --------------------------------------------------------------------------- +// computeBlockingFiles — translation file explicit coverage (Change 1b) +// --------------------------------------------------------------------------- + +describe('computeBlockingFiles — translation files', () => { + const projectMap = { translations: { en: {} } }; + + it('picks up translation file errors even when not in fileResults', () => { + // Simulate: user passed explicit files list without translation files. + // Translation error still in allResults from pos-cli check. + const allResults = { + errors: [ + { + severity: 'error', + _filePath: `${DIR}/app/translations/en.yml`, + check: 'MatchingTranslations', + message: 'Missing key "app.hello" in en', + }, + ], + }; + const result = computeBlockingFiles([], [], allResults, DIR, projectMap); + expect(result).toHaveLength(1); + expect(result[0].path).toBe('app/translations/en.yml'); + expect(result[0].lint_errors).toBe(1); + expect(result[0].checks).toContain('MatchingTranslations'); + }); + + it('does not duplicate translation file already in fileResults', () => { + // fileResults already has it (default discovery path with Change 1a) + const fileResults = [{ path: 'app/translations/en.yml', errors: 2, warnings: 0 }]; + const allResults = { + errors: [ + { severity: 'error', _filePath: `${DIR}/app/translations/en.yml`, check: 'MatchingTranslations', message: 'x' }, + ], + }; + const result = computeBlockingFiles(fileResults, [], allResults, DIR, projectMap); + const entries = result.filter(r => r.path === 'app/translations/en.yml'); + expect(entries).toHaveLength(1); + expect(entries[0].lint_errors).toBe(2); // from fileResults, not allResults + }); + + it('skips translation file when it has no errors in allResults', () => { + const allResults = { errors: [] }; + const result = computeBlockingFiles([], [], allResults, DIR, projectMap); + expect(result).toHaveLength(0); + }); + + it('works without projectDir/projectMap (backward compat)', () => { + const fileResults = [{ path: 'app/a.liquid', errors: 1, warnings: 0 }]; + expect(() => computeBlockingFiles(fileResults, [])).not.toThrow(); + const result = computeBlockingFiles(fileResults, []); + expect(result).toHaveLength(1); + }); +}); diff --git a/tests/unit/dependency-graph.test.js b/tests/unit/dependency-graph.test.js index e3e4604..6f084b3 100644 --- a/tests/unit/dependency-graph.test.js +++ b/tests/unit/dependency-graph.test.js @@ -265,4 +265,15 @@ describe('dependency-graph: detectOrphanedFiles', () => { }; expect(detectOrphanedFiles(graph, map)).toEqual([]); }); + + it('never flags translation files as orphaned — they have no liquid callers by design', () => { + const map = { pages: {}, partials: {}, commands: {}, queries: {} }; + const graph = { + 'app/translations/en.yml': { depends_on: [], referenced_by: [] }, + 'app/translations/de.yml': { depends_on: [], referenced_by: [] }, + }; + const dead = detectOrphanedFiles(graph, map); + expect(dead).not.toContain('app/translations/en.yml'); + expect(dead).not.toContain('app/translations/de.yml'); + }); }); diff --git a/tests/unit/translation-validator.test.js b/tests/unit/translation-validator.test.js index 18a524f..c4957cb 100644 --- a/tests/unit/translation-validator.test.js +++ b/tests/unit/translation-validator.test.js @@ -37,6 +37,17 @@ ecommerce: expect(errors).toHaveLength(1); expect(errors[0].check).toBe('pos-supervisor:TranslationMissingLocaleKey'); }); + + it('errors when top-level key looks like a typo locale (enff, enn, etc.)', () => { + const yaml = `enff: + app: + hello: "Hello" +`; + const { errors } = validate(yaml); + expect(errors).toHaveLength(1); + expect(errors[0].check).toBe('pos-supervisor:TranslationMissingLocaleKey'); + expect(errors[0].message).toMatch(/enff/); + }); }); describe('translation-validator: valid locale wrappers', () => { From f11090d43e9c5548229698e73d4f89439fe34d3b Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Tue, 21 Apr 2026 20:18:37 +0200 Subject: [PATCH 14/20] Integration tests for translations error detection --- src/dashboard.js | 2 +- .../resources/platformos-development-guide.md | 2 + ...validate-code-features.integration.test.js | 40 +++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/dashboard.js b/src/dashboard.js index 5199762..2ecfa0b 100644 --- a/src/dashboard.js +++ b/src/dashboard.js @@ -4788,7 +4788,7 @@ function renderJourneyTimeline(el, j) { return '
' + '
' + t.occurrences + '
' + '
' - + '
' + t.session_id.slice(0, 6) + '
' + + '
' + t.session_id.slice(0, 7) + '
' + '
' + edge; }).join(''); diff --git a/src/data/resources/platformos-development-guide.md b/src/data/resources/platformos-development-guide.md index d63294e..06b0485 100644 --- a/src/data/resources/platformos-development-guide.md +++ b/src/data/resources/platformos-development-guide.md @@ -65,6 +65,8 @@ tools will reject. 6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or `must_fix_before_write: true`, fix every error and re-validate. MUST NOT write the file to disk until validation passes. + When debugging existing files, always read them from disk first and submit + their actual content to `validat_code` tool. 7. Creation order matters: schema → graphql → partial → page. 8. **`analyze_project` — project-wide health check.** MUST be called: - **Before reporting task completion.** `validate_code` only sees one diff --git a/tests/integration/validate-code-features.integration.test.js b/tests/integration/validate-code-features.integration.test.js index 4b3447f..32d2513 100644 --- a/tests/integration/validate-code-features.integration.test.js +++ b/tests/integration/validate-code-features.integration.test.js @@ -140,3 +140,43 @@ slug: test_gotchas_array } }); }); + +// --------------------------------------------------------------------------- +// Translation YAML structural validation +// --------------------------------------------------------------------------- + +describe('validate_code — translation YAML structural errors', () => { + it('reports TranslationMissingLocaleKey when top-level key is not a locale code', async () => { + const content = `enff:\n app:\n hello: "Hello"\n`; + const result = await server.callTool('validate_code', { + file_path: 'app/translations/en.yml', + content, + mode: 'quick', + }); + expect(result.errors.some(e => e.check === 'pos-supervisor:TranslationMissingLocaleKey')).toBe(true); + expect(result.status).toBe('error'); + expect(result.must_fix_before_write).toBe(true); + }); + + it('reports TranslationMissingLocaleKey when tree has no locale wrapper (app: at root)', async () => { + const content = `app:\n contact_form:\n title: "Contact"\n`; + const result = await server.callTool('validate_code', { + file_path: 'app/translations/en.yml', + content, + mode: 'quick', + }); + expect(result.errors.some(e => e.check === 'pos-supervisor:TranslationMissingLocaleKey')).toBe(true); + expect(result.status).toBe('error'); + }); + + it('passes a correctly wrapped translation file', async () => { + const content = `en:\n app:\n hello: "Hello"\n`; + const result = await server.callTool('validate_code', { + file_path: 'app/translations/en.yml', + content, + mode: 'quick', + }); + expect(result.errors.filter(e => e.check === 'pos-supervisor:TranslationMissingLocaleKey')).toHaveLength(0); + expect(result.status).not.toBe('error'); + }); +}); From f112ba418b326896aad58f8a8fea1e175595dfd1 Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Sat, 25 Apr 2026 12:38:44 +0200 Subject: [PATCH 15/20] Analytics overhaul, fix attribution, add overrides & impact panel --- CHANGELOG.md | 121 ++ package.json | 2 +- scripts/cleanup-live-console-rows.js | 94 ++ scripts/rebuild-analytics.js | 57 + src/core/analytics-queries.js | 363 +++++- src/core/analytics-store.js | 275 ++++- src/core/case-base.js | 37 +- src/core/constants.js | 27 + src/core/diagnostic-pipeline.js | 117 ++ src/core/error-enricher.js | 59 + src/core/fix-generator.js | 10 +- src/core/fs-watcher.js | 2 +- src/core/rule-overrides.js | 126 +++ src/core/rules/ConvertIncludeToRender.js | 30 + src/core/rules/ImgLazyLoading.js | 24 + src/core/rules/ImgWidthAndHeight.js | 24 + src/core/rules/NonGetRenderingPage.js | 26 + src/core/rules/engine.js | 86 +- src/core/rules/index.js | 8 + src/core/session-events.js | 11 +- src/core/structural-warnings.js | 85 +- src/core/window-classifier.js | 92 +- src/dashboard.js | 531 ++++++++- .../pos-supervisor:NonGetRenderingPage.md | 33 + ...md~ => ok-platformos-development-guide.md} | 18 +- .../platformos-development-guide-full.md | 25 +- .../resources/platformos-development-guide.md | 639 +---------- .../short-platformos-development-guide.md | 1006 ----------------- src/http-server.js | 160 ++- src/server.js | 36 +- src/tools.js | 14 +- src/tools/validate-code.js | 86 +- .../analytics/fix-rule-attribution.test.js | 94 ++ .../analytics/force-disable-check.test.js | 87 ++ .../structural-rule-attribution.test.js | 76 ++ tests/integration/analytics/untracked.test.js | 135 +++ tests/unit/analytics-queries-k.test.js | 24 +- tests/unit/analytics-queries.test.js | 268 +++++ tests/unit/analytics-store.test.js | 331 +++++- tests/unit/case-base.test.js | 34 +- tests/unit/diagnostic-pipeline.test.js | 114 ++ tests/unit/error-enricher-bridge.test.js | 144 +++ tests/unit/rule-engine-overrides.test.js | 92 ++ tests/unit/rule-overrides.test.js | 79 ++ tests/unit/rules/Tier1Rules.test.js | 79 ++ tests/unit/structural-warnings.test.js | 87 +- tests/unit/window-classifier.test.js | 163 ++- 47 files changed, 4303 insertions(+), 1728 deletions(-) create mode 100644 scripts/cleanup-live-console-rows.js create mode 100644 scripts/rebuild-analytics.js create mode 100644 src/core/rule-overrides.js create mode 100644 src/core/rules/ConvertIncludeToRender.js create mode 100644 src/core/rules/ImgLazyLoading.js create mode 100644 src/core/rules/ImgWidthAndHeight.js create mode 100644 src/core/rules/NonGetRenderingPage.js create mode 100644 src/data/hints/pos-supervisor:NonGetRenderingPage.md rename src/data/resources/{platformos-development-guide.md~ => ok-platformos-development-guide.md} (98%) delete mode 100644 src/data/resources/short-platformos-development-guide.md create mode 100644 tests/integration/analytics/fix-rule-attribution.test.js create mode 100644 tests/integration/analytics/force-disable-check.test.js create mode 100644 tests/integration/analytics/structural-rule-attribution.test.js create mode 100644 tests/integration/analytics/untracked.test.js create mode 100644 tests/unit/error-enricher-bridge.test.js create mode 100644 tests/unit/rule-engine-overrides.test.js create mode 100644 tests/unit/rule-overrides.test.js create mode 100644 tests/unit/rules/Tier1Rules.test.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e81122..d534992 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,126 @@ # Changelog +## 0.6.0 — 2026-04-24 + +Analytics pipeline overhaul + neuro-symbolic engine rounds out. Headline numbers on the DEMO project between 2026-04-23 and 2026-04-24: fix-proposal rate rose from effectively 0 (the emit loop was reading the wrong field) to 45 / 99 (45%); classified fix adoption rose from 0 to 31; confidence coverage from 0% to 89% of emits; rule performance table from 3 entries at baseline to 30+; health score from 91 to 95/100. + +### Fixed — three critical analytics bugs + +- **`outcomes.fix_applied` was always null.** The classifier (`classifyFixAdoption`) existed in `window-classifier.js` but no call site. Wired it into `analytics-store.classifyAndStoreWindows()` using `buildEmitIndex` + blobStore content lookup. Start-of-window emit picks the proposed-fix set the agent actually saw; `regressed` / `write_unverified` outcomes skipped (no semantic meaning). `openAnalyticsStore(dbPath, { blobStore })` now accepts the blob store; `server.js` and `scripts/rebuild-analytics.js` pass it through. +- **`hint_md_hash` emitted but dropped on ingest.** No column existed on `diagnostics`. Schema bumped to v5 with `migrate_v4_to_v5` adding the column; ingestion persists the hash; `diagnosticJourney` + `ruleDrilldown` surface it; dashboard code-context panel renders the hint blob alongside the file window. +- **Heuristic fix-generator fixes never reached analytics.** Emit loop read `d.fixes` (rule-engine channel) but the heuristic generator writes to `d.fix` (singular). Unioned both channels; every fix now persisted with its attribution. + +### Added — Phases A1–A4 (analytics integrity) + +- **A1 — outcome dedup.** `outcomes` table carries UNIQUE(session_id, file, fp); `INSERT OR REPLACE` stamps terminal state as `classifySession` walks windows. Migration `migrate_v1_to_v2` dedups existing rows by MAX(id), drops orphans, adds the index. Resolution > Emit mismatch eliminated. +- **A2 — confidence defaults.** `DEFAULT_CONFIDENCE_BY_SEVERITY = { error: 0.9, warning: 0.7, info: 0.5 }` + `STRUCTURAL_DEFAULT_CONFIDENCE = 0.75`. New pipeline step `populateDefaultConfidence` (step 17) fills any missing confidence and stamps `${check}.unmatched` rule_id fallback. Exported as `stampDefaultsOn(result)` for validate-code to re-run after late structural-warning pushes. +- **A3 — `_source: 'dashboard_live'` untracked gate.** Live Diagnostic Console calls no longer pollute analytics. `tools.js` sets `ctx.untracked = true` on a per-call context copy (restore-in-finally); `validate-code.js` gates `sessionBus.emit('validator_emit', ...)` on `!ctx.untracked`. One-off cleanup script for pre-A3 pollution in `scripts/cleanup-live-console-rows.js`. +- **A4 — rule attribution.** `${check}.unmatched` fallback lands in rule_id when no rule fires. `rulePerformance(store, { minEmitted = 1 })` separate reporting-view query, groups on rule_id including `.unmatched`, exposes `source` and `unmatched` flag. `ruleScores()` stays at minEmitted=5 with `.unmatched` excluded for promotion gating. + +### Added — I1 heuristic + rule fix attribution + +- Schema v6 + `proposed_fixes.rule_id` column + `idx_fixes_rule` index + `migrate_v5_to_v6`. +- Central stamp in `fix-generator.js`: every heuristic fix tagged `heuristic:.` in one place (no per-branch boilerplate). +- Emit loop propagates fix-level rule_id with `f.rule_id ?? d.rule_id ?? null` fallback — rule-engine rules attach rule_id to the HintResult rather than each fix, so fixes inherit from the diagnostic. +- New `fixRulePerformance(store, { minProposed = 1 })` query groups on `proposed_fixes.rule_id`, returns `{ rule_id, source, fix_kind, proposed, outcomes, adopted_verbatim, adopted_partial, adoption_rate, resolution_rate }`. +- HTTP endpoint `GET /api/analytics/fix-rule-performance`. + +### Added — Part G adaptive-mode impact panel + +- `adaptiveModeImpact(store, { windowMs = 86400000 })` returns window-scoped emit counts, rule-matched counts, confidence stats, and an `emits_by_rule` map for counterfactual calculation. +- HTTP `GET /api/engine/impact` merges the query with live engine state (`getDisabledRuleDetails`, force-enable/disable sets) and computes `suppressed_by_disabled` counterfactual. +- Dashboard — new "Adaptive Mode Impact" section in the Engine Map tab: summary stat tiles, disabled-rules table with per-row action buttons, force-enabled / force-disabled chip lists. + +### Added — I4 manual rule overrides + +- `src/core/rule-overrides.js` module. Persists `.pos-supervisor/rule-overrides.json` (atomic write via temp + rename, tolerant read). API: `loadOverrides`, `saveOverrides`, `addForceEnable`, `addForceDisable`, `removeOverride`, `overrideSets`. +- Engine — `_forceEnabled` and `_forceDisabled` sets. `ruleIsActive()` precedence: `force_disable > force_enable > _disabledRules`. New `isCheckForceDisabled(checkName)` also gates structural / LSP-only checks by name. +- Validate-code filter step drops diagnostics whose `check` or `rule_id` is in the force-disable set — structural checks like `pos-supervisor:HtmlInPage` can be killed without waiting for the auto-disable threshold. +- HTTP `GET` and `POST /api/engine/rule-overrides` with `{ action, rule_id, reason }` where action is `force_enable | force_disable | clear`. `onOverridesChanged` hook refreshes the engine without restart. +- Dashboard — override-add form (input + reason + FE/FD buttons) with HTML5 `` autocomplete populated from rule-performance data + derived check names. + +### Added — late-push attribution bridge + +- `bridgeRulesOntoUnattributed(result, ctx)` in `error-enricher.js`. Runs `runRules` on any diagnostic whose `rule_id` is still unset and whose `check` has a registered rule module. Copies `rule_id`, `hint_md`, `confidence`, `see_also`, `fixes`, `case_base_signal` onto the diagnostic. Idempotent. Rule failures non-fatal. +- Called from `validate-code.js` after all late-push sources (structural warnings, schema/translation validators, diff-aware checks, new-partial caller check) and before `stampDefaultsOn`. Structural `pos-supervisor:*` rules now get their canonical rule_id instead of landing in `.unmatched`. + +### Added — engine-map write-closed windows + draft detection + +- `classifyWriteWindow(validateCall, writeEvent)` and `extractWriteEvents(events)` in `window-classifier.js`. +- Schema v4 adds `windows.is_draft` and `windows.closed_by ∈ {'validate','write'}`. Validate-to-validate windows with no intervening disk write are tagged `is_draft = 1` (measures thinking, not effectiveness). +- `fs-watcher.js` emits `rel_path` alongside `path` so the classifier can match writes to validated files. + +### Added — Tier 1 rule modules + +- `src/core/rules/ImgLazyLoading.js` (rule_id `ImgLazyLoading.recommended`). +- `src/core/rules/ImgWidthAndHeight.js` (rule_id `ImgWidthAndHeight.recommended`). +- `src/core/rules/ConvertIncludeToRender.js` (rule_id `ConvertIncludeToRender.default`). + +Each provides attribution + an action-oriented hint. Fix text stays with the heuristic generator (single source of truth on AST position math); the rules return `fixes: []` and rely on the `heuristic:.text_edit` channel. Registered via `src/core/rules/index.js`. + +### Added — new structural checks + +- **`pos-supervisor:NonGetRenderingPage`** — warns when a page has `method: post/put/delete/patch` AND renders HTML (layout, partials, `{{ }}` output, or HTML tags present). Catches the agent-confusion pattern of setting `method: post` on landing pages, which makes them 404 on browser GET. Suppressed when slug starts with `/api/`, `/_/`, `/internal/` OR the body has no UI signals (pure JSON/redirect endpoint). Rule module `NonGetRenderingPage.default` + hint file `src/data/hints/pos-supervisor:NonGetRenderingPage.md` with a landing-page vs API-endpoint decision tree. +- **`verifyMissingPartialsOnDisk`** pipeline step — cross-check `MissingPartial` diagnostics against the real filesystem; suppress when the partial exists on disk but the LSP hasn't re-indexed yet (handles scaffold write → re-validate timing race). + +### Changed + +- **`pos-supervisor:HtmlInPage` guard** — suppress when the page renders at least one partial (composite landing-page pattern). Production showed 100% regression on this rule before the guard. +- **`pos-supervisor:MissingDocBlock` scope** — dropped commands branch (production showed 40% regression on `commands/`; many internal helpers legitimately don't need doc blocks). Partials only now. +- **Validate-code emit loop** — propagates `rule_id` on every fix; unions rule + heuristic fixes; re-runs `stampDefaultsOn` after all late-push sources so confidence / rule_id coverage is complete. + +### Added — dashboard features + +- **Code-context panel in rule drilldown**: fetches content blob (`GET /api/blob?hash=…`), fix blob, and hint blob in parallel; renders a 40-line window around `fix_range` with the error line highlighted; Proposed fix + Hint blocks below. New `/api/blob` endpoint with 64-hex SHA256 validation. +- **Journey timeline clickable nodes**: click a session dot to open the same code-context panel inline. +- **Confidence column** in the rule-drilldown samples table, color-coded (≥0.8 green, ≥0.5 yellow, else red; `n/a` muted). +- **Live-console file picker** stays in sync with validation SSE activity (`addToLivePickerFiles` / `removeFromLivePickerFiles`) — no longer requires an Explorer tab refresh to see newly-validated files. + +### Added — scripts + +- **`scripts/rebuild-analytics.js`** — rebuild the analytics DB from session event logs. Injects the blob store so fix-adoption classification runs on replay. +- **`scripts/cleanup-live-console-rows.js`** — one-off purge of pre-A3 `__pos_live_console__` rows from events/diagnostics/outcomes/windows/proposed_fixes. + +### Added — tests + +New unit test files: + +- `tests/unit/error-enricher-bridge.test.js` — 6 cases covering bridge idempotency, no-rule-module no-op, missing fact-graph no-op, errors/warnings/infos, rule-throws non-fatal. +- `tests/unit/rule-overrides.test.js` — 7 cases: round-trip, malformed JSON, mutual exclusion. +- `tests/unit/rule-engine-overrides.test.js` — 7 cases: force precedence, check-name gating, engine-state reset. +- `tests/unit/rules/Tier1Rules.test.js` — 4 rule-module tests (ImgLazy, ImgW&H, ConvertInclude, NonGetRenderingPage). + +Extended unit files: `analytics-store.test.js`, `analytics-queries.test.js`, `analytics-queries-k.test.js`, `diagnostic-pipeline.test.js`, `structural-warnings.test.js`, `window-classifier.test.js`, `case-base.test.js`. + +New integration tests in `tests/integration/analytics/`: + +- `untracked.test.js` — A3 gate. +- `fix-rule-attribution.test.js` — I1 follow-up rule-engine inheritance. +- `force-disable-check.test.js` — I4 override semantics end-to-end (POST + clear). +- `structural-rule-attribution.test.js` — bridge end-to-end (NonGetRenderingPage lands as `.default`, not `.unmatched`). + +**Suite totals: 1635 unit + 25 analytics/http/workflows integration, all green.** + +### Changed — plan doc + +- `docs/new-task/implementation-plan.md` — new "Addendum — 2026-04-23" section: I1 (heuristic rule attribution), I2 (see_also_followed outcome), I3 (soak fresh data), I4 (manual rule re-enable + dashboard visibility). Revised short-term order with Part G + I4 bumped up. + +### Migrations + +DB schema: **v1 → v6** via five numbered, idempotent steps. No backfills write data — only reshape tables. A `store.rebuild(sessionsDir)` against the existing event log repopulates the new columns. + +- **v1 → v2**: dedup outcomes + add UNIQUE(session, file, fp) index + add `session_id` / `file` columns + backfill from windows. +- **v2 → v3**: dedup diagnostics + add UNIQUE(session, file, fp) index. +- **v3 → v4**: add `windows.is_draft` + `windows.closed_by`. +- **v4 → v5**: add `diagnostics.hint_md_hash`. +- **v5 → v6**: add `proposed_fixes.rule_id` + `idx_fixes_rule`. + +### Upgrade notes + +1. `pkill -f bin/pos-supervisor.js && bun bin/pos-supervisor.js` — new schema migrations run on first open. +2. Optional: `bun scripts/rebuild-analytics.js /path/to/project` — replays the event log into the new columns so historical sessions gain confidence / hint_md_hash / fix rule_id attribution. +3. Optional: `bun scripts/cleanup-live-console-rows.js /path/to/project` — purge pre-A3 live-console pollution if the DB predates this release. + ## 0.5.2 ### Added diff --git a/package.json b/package.json index 3e212ce..4422968 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@platformos/pos-supervisor", - "version": "0.5.2", + "version": "0.6.0", "description": "platformOS domain-specific MCP server for LLM agents", "type": "module", "bin": { diff --git a/scripts/cleanup-live-console-rows.js b/scripts/cleanup-live-console-rows.js new file mode 100644 index 0000000..44e282e --- /dev/null +++ b/scripts/cleanup-live-console-rows.js @@ -0,0 +1,94 @@ +#!/usr/bin/env bun +/** + * One-off cleanup — remove analytics rows that originated from the dashboard + * Live Diagnostic Console before A3 introduced the `untracked` gate. + * + * Symptom those rows caused: `__pos_live_console__` files appearing in the + * `OrphanedPartial` and `pos-supervisor:MissingDocBlock` file distributions + * of the supervisor report. Every live-console validation wrote a + * `validator_emit` that the store replayed into diagnostics/outcomes. + * + * Usage: + * bun scripts/cleanup-live-console-rows.js [/path/to/project] + * + * Project path defaults to POS_SUPERVISOR_PROJECT_DIR or the current working + * directory. Runs against `.pos-supervisor/analytics.db` under that project. + * + * Safe to re-run — purely a DELETE of rows whose file column matches the + * live-console sentinel. No schema changes. + */ + +import { join, resolve } from 'node:path'; +import { existsSync } from 'node:fs'; +import { openAnalyticsStore } from '../src/core/analytics-store.js'; + +const LIVE_CONSOLE_NEEDLE = '__pos_live_console__'; + +function parseArgs() { + const projectArg = process.argv[2]; + const projectDir = resolve(projectArg ?? process.env.POS_SUPERVISOR_PROJECT_DIR ?? process.cwd()); + return { projectDir }; +} + +function main() { + const { projectDir } = parseArgs(); + const dbPath = join(projectDir, '.pos-supervisor', 'analytics.db'); + + if (!existsSync(dbPath)) { + console.error(`No analytics DB at ${dbPath}. Nothing to clean.`); + process.exit(0); + } + + const store = openAnalyticsStore(dbPath); + const db = store.db; + + const beforeCounts = { + events: db.prepare(`SELECT COUNT(*) AS n FROM events WHERE payload LIKE ?`).get(`%${LIVE_CONSOLE_NEEDLE}%`).n, + diagnostics: db.prepare(`SELECT COUNT(*) AS n FROM diagnostics WHERE file LIKE ?`).get(`%${LIVE_CONSOLE_NEEDLE}%`).n, + outcomes: db.prepare(`SELECT COUNT(*) AS n FROM outcomes WHERE file LIKE ?`).get(`%${LIVE_CONSOLE_NEEDLE}%`).n, + windows: db.prepare(`SELECT COUNT(*) AS n FROM windows WHERE file LIKE ?`).get(`%${LIVE_CONSOLE_NEEDLE}%`).n, + proposed_fixes: db.prepare( + `SELECT COUNT(*) AS n FROM proposed_fixes pf + WHERE EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = pf.fp AND d.file LIKE ?)`, + ).get(`%${LIVE_CONSOLE_NEEDLE}%`).n, + }; + + db.exec('BEGIN'); + try { + db.prepare( + `DELETE FROM proposed_fixes + WHERE fp IN (SELECT fp FROM diagnostics WHERE file LIKE ?)`, + ).run(`%${LIVE_CONSOLE_NEEDLE}%`); + + db.prepare( + `DELETE FROM outcomes WHERE file LIKE ?`, + ).run(`%${LIVE_CONSOLE_NEEDLE}%`); + + db.prepare( + `DELETE FROM windows WHERE file LIKE ?`, + ).run(`%${LIVE_CONSOLE_NEEDLE}%`); + + db.prepare( + `DELETE FROM diagnostics WHERE file LIKE ?`, + ).run(`%${LIVE_CONSOLE_NEEDLE}%`); + + db.prepare( + `DELETE FROM events WHERE payload LIKE ?`, + ).run(`%${LIVE_CONSOLE_NEEDLE}%`); + + db.exec('COMMIT'); + } catch (e) { + db.exec('ROLLBACK'); + console.error('Cleanup failed; rolled back.'); + throw e; + } + + console.log(`Removed live-console rows from ${dbPath}:`); + for (const [table, count] of Object.entries(beforeCounts)) { + console.log(` ${table.padEnd(16)} ${count}`); + } + + store.close(); +} + +main(); diff --git a/scripts/rebuild-analytics.js b/scripts/rebuild-analytics.js new file mode 100644 index 0000000..84bfe36 --- /dev/null +++ b/scripts/rebuild-analytics.js @@ -0,0 +1,57 @@ +#!/usr/bin/env node +/** + * Rebuild the analytics DB from session event logs. + * + * Usage: + * node scripts/rebuild-analytics.js /path/to/project + * + * The project must have a .pos-supervisor/ directory with sessions/ and analytics.db. + * The server must NOT be running when this script executes (WAL mode allows reads + * but schema migrations can conflict with a live server). + */ + +import { join } from 'node:path'; +import { existsSync } from 'node:fs'; +import { openAnalyticsStore } from '../src/core/analytics-store.js'; +import { openBlobStore } from '../src/core/blob-store.js'; + +const projectDir = process.argv[2]; +if (!projectDir) { + console.error('Usage: node scripts/rebuild-analytics.js /path/to/project'); + process.exit(1); +} + +const supervisorDir = join(projectDir, '.pos-supervisor'); +const dbPath = join(supervisorDir, 'analytics.db'); +const sessionsDir = join(supervisorDir, 'sessions'); +const blobsDir = join(supervisorDir, 'blobs'); + +if (!existsSync(supervisorDir)) { + console.error(`No .pos-supervisor directory found at: ${supervisorDir}`); + process.exit(1); +} +if (!existsSync(sessionsDir)) { + console.error(`No sessions directory found at: ${sessionsDir}`); + process.exit(1); +} + +console.log(`DB: ${dbPath}`); +console.log(`Sessions: ${sessionsDir}`); +console.log(`Blobs: ${blobsDir}`); +console.log('Rebuilding...'); + +// Blob store is required for fix-adoption classification (reads start/end file +// snapshots and proposed-fix texts). Without it, every outcome row lands with +// fix_applied = null. Fine if the blobs dir doesn't exist yet — classification +// just degrades to null for that session. +let blobStore = null; +try { + blobStore = openBlobStore(blobsDir); +} catch (e) { + console.warn(`Blob store unavailable (${e.message}); fix adoption will not be classified.`); +} + +const store = openAnalyticsStore(dbPath, { blobStore }); +const { sessions, events } = store.rebuild(sessionsDir); + +console.log(`Done. Replayed ${events} events across ${sessions} sessions.`); diff --git a/src/core/analytics-queries.js b/src/core/analytics-queries.js index 76940b3..26f012b 100644 --- a/src/core/analytics-queries.js +++ b/src/core/analytics-queries.js @@ -9,6 +9,11 @@ const MIN_COHORT = 10; +function tryParseJson(str) { + if (!str) return null; + try { return JSON.parse(str); } catch { return null; } +} + /** * Beta-binomial posterior: given `successes` out of `total` trials * with prior Beta(a, b), return { mean, lower95, upper95 }. @@ -319,11 +324,14 @@ export function diagnosticJourney(store, templateFp) { SELECT d.session_id, d.ts, d.hint_rule_id, + d.hint_md_hash, d.fp, + d.content_hash, + d.file, o.outcome, o.fix_applied FROM diagnostics d - LEFT JOIN outcomes o ON o.fp = d.fp + LEFT JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.template_fp = ? AND d.suppressed = 0 ORDER BY d.ts ASC `, [templateFp]); @@ -337,12 +345,35 @@ export function diagnosticJourney(store, templateFp) { occurrences: 0, rule_id: null, outcomes: [], + content_hash: null, + hint_md_hash: null, + fp: null, + file: null, }); } const entry = bySession.get(row.session_id); entry.occurrences++; if (row.hint_rule_id && row.hint_rule_id !== 'unknown') entry.rule_id = row.hint_rule_id; if (row.outcome) entry.outcomes.push({ outcome: row.outcome, fix_applied: row.fix_applied ?? null }); + if (row.content_hash && !entry.content_hash) { + entry.content_hash = row.content_hash; + entry.fp = row.fp; + entry.file = row.file; + } + if (row.hint_md_hash && !entry.hint_md_hash) { + entry.hint_md_hash = row.hint_md_hash; + } + } + + // Fetch fix data for each session entry that has a diagnostic fingerprint. + for (const entry of bySession.values()) { + if (!entry.fp) continue; + const fixRow = store.queryOne(` + SELECT new_text_hash, range_json FROM proposed_fixes + WHERE fp = ? AND session_id = ? LIMIT 1 + `, [entry.fp, entry.session_id]); + entry.fix_hash = fixRow?.new_text_hash ?? null; + entry.fix_range = tryParseJson(fixRow?.range_json); } const timeline = [...bySession.values()].map(s => { @@ -360,6 +391,11 @@ export function diagnosticJourney(store, templateFp) { rule_id: s.rule_id, dominant_outcome: dominant, fix_applied: s.outcomes.find(o => o.fix_applied)?.fix_applied ?? null, + content_hash: s.content_hash ?? null, + hint_md_hash: s.hint_md_hash ?? null, + fix_hash: s.fix_hash ?? null, + fix_range: s.fix_range ?? null, + file: s.file ?? null, }; }); @@ -384,11 +420,16 @@ export function diagnosticJourney(store, templateFp) { * @returns {Array<{ bucket, predicted, actual_resolution, sample_size }>} */ export function confidenceCalibration(store, { buckets = 10 } = {}) { + // Post-A2: every surviving diagnostic gets a default confidence in the + // pipeline, so dropping the `confidence IS NOT NULL` guard widens the + // calibration sample to cover non-rule-matched diagnostics too. Rows + // predating A2 (no pipeline default) will have NULL confidence — exclude + // those explicitly so the bucketing math doesn't see NaN. const rows = store.query(` SELECT d.confidence, o.outcome FROM diagnostics d - JOIN outcomes o ON o.fp = d.fp - WHERE d.confidence IS NOT NULL AND d.suppressed = 0 + JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file + WHERE d.suppressed = 0 AND d.confidence IS NOT NULL `); if (rows.length === 0) return []; @@ -445,11 +486,14 @@ export function fixAdoptionFunnel(store) { `); const fix_proposed = fixProposedRow?.cnt ?? 0; + // Post-A1 (dedup): outcomes has one row per (session, file, fp). A plain + // JOIN to diagnostics on fp cross-joins by emit count — use EXISTS to + // keep the count at one-per-outcome-row. const fixAdoptionRows = store.query(` SELECT o.fix_applied, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp - WHERE d.suppressed = 0 AND o.fix_applied IS NOT NULL + WHERE o.fix_applied IS NOT NULL + AND EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0) GROUP BY o.fix_applied `); let fix_adopted_verbatim = 0, fix_adopted_partial = 0, fix_ignored = 0; @@ -462,8 +506,7 @@ export function fixAdoptionFunnel(store) { const outcomeRows = store.query(` SELECT o.outcome, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp - WHERE d.suppressed = 0 + WHERE EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0) GROUP BY o.outcome `); let resolved = 0, regressed = 0, unchanged = 0; @@ -500,7 +543,7 @@ export function ruleScoresByCategory(store) { d.file, o.outcome FROM diagnostics d - JOIN outcomes o ON o.fp = d.fp + JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.hint_rule_id IS NOT NULL AND d.hint_rule_id != 'unknown' AND d.suppressed = 0 `); @@ -527,12 +570,12 @@ export function ruleScoresByCategory(store) { function classifyFilePath(file) { if (!file) return 'other'; - if (file.includes('/pages/') || file.includes('/layouts/')) return 'pages'; - if (file.includes('/partials/') || file.includes('/lib/')) return 'partials'; - if (file.includes('/commands/') || file.includes('/mutations/')) return 'commands'; - if (file.includes('/queries/')) return 'queries'; - if (file.endsWith('.graphql') || file.includes('/graphql/')) return 'graphql'; - if (file.includes('/schema/') || file.endsWith('.yml') || file.endsWith('.yaml')) return 'schema'; + if (file.startsWith('app/views/pages/') || file.startsWith('app/views/layouts/')) return 'pages'; + if (file.startsWith('app/views/partials/')) return 'partials'; + if (file.startsWith('app/lib/commands/') || file.includes('/mutations/')) return 'commands'; + if (file.startsWith('app/lib/queries/')) return 'queries'; + if (file.endsWith('.graphql') || file.startsWith('app/graphql/')) return 'graphql'; + if (file.startsWith('app/schema/') || file.endsWith('.yml') || file.endsWith('.yaml')) return 'schema'; return 'other'; } @@ -560,7 +603,7 @@ export function knowledgeGaps(store) { SELECT COUNT(*) as total, SUM(CASE WHEN o.outcome = 'resolved' THEN 1 ELSE 0 END) as resolved FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp + JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.check_name = ? AND d.suppressed = 0 `, [row.check_name]); @@ -577,20 +620,110 @@ export function knowledgeGaps(store) { }); } +/** + * Rule performance — **reporting view.** + * + * Mirror of `ruleScores()` (case-base.js) but intended for dashboards and + * reports, not promotion decisions: + * - Default threshold 1 (not 5): surface every rule that fired at least + * once so operators can see the long tail, including brand-new rules. + * - Includes `${check}.unmatched` fallback rule_ids (set by the pipeline + * for rule-less diagnostics — A4). These don't correspond to a + * registered rule, but they belong in reporting so the coverage gap is + * visible. + * - Omits the `disabled` flag. Disabling is a promotion decision; reports + * shouldn't imply one by displaying a derived threshold label. + * - Uses `EXISTS` for the outcome join. Post-A1 `outcomes` carries one row + * per (session, file, fp); a plain JOIN cross-multiplies with per-emit + * diagnostic rows. EXISTS keeps counts at one-per-outcome. + * + * @param {object} store + * @param {object} [opts] + * @param {number} [opts.minEmitted=1] + * @returns {Array} + */ +export function rulePerformance(store, { minEmitted = 1 } = {}) { + const ruleRows = store.query(` + SELECT d.hint_rule_id as rule_id, + COUNT(*) as emitted, + MIN(d.check_name) as check_name + FROM diagnostics d + WHERE d.hint_rule_id IS NOT NULL + AND d.hint_rule_id != 'unknown' + AND d.suppressed = 0 + GROUP BY d.hint_rule_id + HAVING COUNT(*) >= ? + `, [minEmitted]); + + const scores = []; + + for (const row of ruleRows) { + const outcomeRows = store.query(` + SELECT o.outcome, o.fix_applied, COUNT(*) as cnt + FROM outcomes o + WHERE EXISTS ( + SELECT 1 FROM diagnostics d + WHERE d.fp = o.fp AND d.hint_rule_id = ? AND d.suppressed = 0 + ) + GROUP BY o.outcome, o.fix_applied + `, [row.rule_id]); + + let resolved = 0, regressed = 0, unchanged = 0, moved = 0; + let adopted = 0, totalOutcomes = 0; + + for (const o of outcomeRows) { + totalOutcomes += o.cnt; + if (o.outcome === 'resolved') resolved += o.cnt; + else if (o.outcome === 'regressed') regressed += o.cnt; + else if (o.outcome === 'unchanged') unchanged += o.cnt; + else if (o.outcome === 'moved') moved += o.cnt; + if (o.fix_applied === 'verbatim') adopted += o.cnt; + } + + const resolutionRate = totalOutcomes > 0 ? resolved / totalOutcomes : 0; + const regressionRate = totalOutcomes > 0 ? regressed / totalOutcomes : 0; + const adoptionRate = totalOutcomes > 0 ? adopted / totalOutcomes : 0; + const effectiveness = resolutionRate - regressionRate; + + scores.push({ + rule_id: row.rule_id, + check: row.check_name, + emitted: row.emitted, + total_outcomes: totalOutcomes, + resolved, + regressed, + unchanged, + moved, + adopted, + resolution_rate: resolutionRate, + regression_rate: regressionRate, + adoption_rate: adoptionRate, + effectiveness, + unmatched: row.rule_id.endsWith('.unmatched'), + }); + } + + scores.sort((a, b) => a.effectiveness - b.effectiveness); + return scores; +} + /** * Rule drilldown — detailed diagnostic samples for a specific rule. * Returns recent instances where this rule fired, with outcomes, fix status, * and file distribution. Used by the dashboard drill-down panel. */ export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) { - // Each diagnostic row gets at most one outcome via a correlated subquery, + // Each diagnostic row gets at most one outcome via correlated subqueries, // avoiding the cartesian product from a plain LEFT JOIN on fp. const samples = store.query(` SELECT d.rowid as did, d.fp, d.template_fp, d.file, d.check_name, d.ts, - d.confidence, d.session_id, - (SELECT o.outcome FROM outcomes o WHERE o.fp = d.fp ORDER BY o.id DESC LIMIT 1) as outcome, - (SELECT o.fix_applied FROM outcomes o WHERE o.fp = d.fp ORDER BY o.id DESC LIMIT 1) as fix_applied, - (SELECT o.collateral_added FROM outcomes o WHERE o.fp = d.fp ORDER BY o.id DESC LIMIT 1) as collateral_added + d.confidence, d.session_id, d.content_hash, d.hint_md_hash, + (SELECT o.outcome FROM outcomes o WHERE o.fp = d.fp AND o.session_id = d.session_id ORDER BY o.id DESC LIMIT 1) as outcome, + (SELECT o.fix_applied FROM outcomes o WHERE o.fp = d.fp AND o.session_id = d.session_id ORDER BY o.id DESC LIMIT 1) as fix_applied, + (SELECT o.collateral_added FROM outcomes o WHERE o.fp = d.fp AND o.session_id = d.session_id ORDER BY o.id DESC LIMIT 1) as collateral_added, + (SELECT pf.new_text_hash FROM proposed_fixes pf WHERE pf.fp = d.fp AND pf.session_id = d.session_id LIMIT 1) as fix_hash, + (SELECT pf.range_json FROM proposed_fixes pf WHERE pf.fp = d.fp AND pf.session_id = d.session_id LIMIT 1) as fix_range_json, + (SELECT pf.rule_id FROM proposed_fixes pf WHERE pf.fp = d.fp AND pf.session_id = d.session_id LIMIT 1) as fix_rule_id FROM diagnostics d WHERE d.hint_rule_id = ? AND d.suppressed = 0 GROUP BY d.fp, d.session_id @@ -645,6 +778,11 @@ export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) { outcome: s.outcome ?? null, fix_applied: s.fix_applied ?? null, collateral: s.collateral_added ?? 0, + content_hash: s.content_hash ?? null, + hint_md_hash: s.hint_md_hash ?? null, + fix_hash: s.fix_hash ?? null, + fix_range: tryParseJson(s.fix_range_json), + fix_rule_id: s.fix_rule_id ?? null, })), file_distribution: fileStats.map(f => ({ file: f.file, @@ -661,3 +799,188 @@ export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) { })), }; } + +/** + * I1 — heuristic + rule fix-proposal performance. + * + * Reports per-rule_id stats grouped by `proposed_fixes.rule_id`. Covers BOTH + * rule-engine rules (e.g. "UnknownFilter.suggest_nearest") and heuristic- + * generator variants (e.g. "heuristic:UnknownFilter.text_edit"). Complements + * `rulePerformance()`, which groups on `diagnostics.hint_rule_id` — that one + * measures rule *matching*, this one measures fix *proposal / adoption*. + * + * Uses EXISTS when joining back to diagnostics so post-A1 outcome dedup isn't + * re-inflated by multiple emit rows sharing the same fp. + * + * @param {object} store + * @param {object} [opts] + * @param {number} [opts.minProposed=1] + * @returns {Array<{ + * rule_id, source, fix_kind, + * proposed, outcomes, adopted_verbatim, adopted_partial, + * adoption_rate, resolution_rate, + * }>} + */ +export function fixRulePerformance(store, { minProposed = 1 } = {}) { + const rows = store.query(` + SELECT pf.rule_id, + MIN(pf.kind) AS fix_kind, + COUNT(*) AS proposed + FROM proposed_fixes pf + WHERE pf.rule_id IS NOT NULL + GROUP BY pf.rule_id + HAVING COUNT(*) >= ? + `, [minProposed]); + + const out = []; + for (const r of rows) { + const outcomeRows = store.query(` + SELECT o.outcome, o.fix_applied, COUNT(*) AS n + FROM outcomes o + WHERE EXISTS ( + SELECT 1 FROM proposed_fixes pf + WHERE pf.fp = o.fp AND pf.session_id = o.session_id AND pf.rule_id = ? + ) + GROUP BY o.outcome, o.fix_applied + `, [r.rule_id]); + + let resolved = 0, regressed = 0, unchanged = 0, moved = 0; + let adopted_verbatim = 0, adopted_partial = 0, adopted_none = 0, total = 0; + for (const o of outcomeRows) { + total += o.n; + if (o.outcome === 'resolved') resolved += o.n; + else if (o.outcome === 'regressed') regressed += o.n; + else if (o.outcome === 'unchanged') unchanged += o.n; + else if (o.outcome === 'moved') moved += o.n; + + if (o.fix_applied === 'verbatim') adopted_verbatim += o.n; + else if (o.fix_applied === 'partial') adopted_partial += o.n; + else adopted_none += o.n; + } + + const source = r.rule_id.startsWith('heuristic:') ? 'heuristic' : 'rule'; + out.push({ + rule_id: r.rule_id, + source, + fix_kind: r.fix_kind, + proposed: r.proposed, + outcomes: total, + resolved, + regressed, + unchanged, + moved, + adopted_verbatim, + adopted_partial, + adopted_none, + adoption_rate: total ? (adopted_verbatim + adopted_partial) / total : 0, + resolution_rate: total ? resolved / total : 0, + }); + } + + out.sort((a, b) => b.proposed - a.proposed); + return out; +} + +/** + * Part G — adaptive-mode impact summary. + * + * Answers "what is adaptive mode actually doing right now, and what would + * static mode have done differently?" Two halves: + * + * 1. Current adaptive state: + * - which rules are disabled (+ their scores & outcome counts) + * - active force-enable / force-disable overrides + * - avg |adaptive_confidence - raw_confidence| over the last N emits + * (measures how aggressively case-base is bending scores) + * + * 2. Counterfactual for the recent window: + * - diagnostics suppressed by auto-disable (would have been surfaced + * under static mode) + * - fix proposals contributed by promoted rules (would be missing under + * static mode — promoted rules only exist in adaptive) + * - net delta headline for the dashboard summary row + * + * The query itself is schema-only — it doesn't touch the engine. The caller + * (server.js → /api/engine/impact) merges in the live engine state + * (`getDisabledRuleDetails`, override sets, `listPromotedRules`) that isn't + * in the DB. + * + * @param {object} store + * @param {object} [opts] + * @param {number} [opts.windowMs=86400000] Look-back window, default 24h. + * @returns {{ + * window_ms, window_start, window_end, + * emits_in_window, rule_matched_in_window, + * avg_confidence_delta, + * confidence_delta_samples, + * suppressed_by_disabled, + * promoted_fix_contributions + * }} + */ +export function adaptiveModeImpact(store, { windowMs = 86400000 } = {}) { + const windowEnd = new Date().toISOString(); + const windowStart = new Date(Date.now() - windowMs).toISOString(); + + const emitsRow = store.queryOne(` + SELECT COUNT(*) AS cnt + FROM diagnostics + WHERE ts BETWEEN ? AND ? AND suppressed = 0 + `, [windowStart, windowEnd]); + + const ruleMatchedRow = store.queryOne(` + SELECT COUNT(*) AS cnt + FROM diagnostics + WHERE ts BETWEEN ? AND ? + AND suppressed = 0 + AND hint_rule_id IS NOT NULL + AND hint_rule_id != 'unknown' + AND hint_rule_id NOT LIKE '%.unmatched' + `, [windowStart, windowEnd]); + + // avg |adaptive - raw| is not computable from the DB — the store only + // records the final confidence. To surface *some* adjustment signal we + // return the spread of confidence values across rule-matched diagnostics + // in the window, which moves when case-base scoring bends confidences. + const confRow = store.queryOne(` + SELECT COUNT(*) AS n, + AVG(confidence) AS mean, + MIN(confidence) AS min_c, + MAX(confidence) AS max_c + FROM diagnostics + WHERE ts BETWEEN ? AND ? + AND suppressed = 0 + AND confidence IS NOT NULL + AND hint_rule_id NOT LIKE '%.unmatched' + `, [windowStart, windowEnd]); + + // Counterfactual: diagnostics whose hint_rule_id is in the currently- + // disabled set. The query can't know the live disabled set — it's set + // from the engine at call time — so we return a helper sub-query result + // keyed by rule_id that the caller filters. + const byRuleRows = store.query(` + SELECT hint_rule_id AS rule_id, COUNT(*) AS n + FROM diagnostics + WHERE ts BETWEEN ? AND ? AND suppressed = 0 + GROUP BY hint_rule_id + `, [windowStart, windowEnd]); + const byRule = {}; + for (const r of byRuleRows) if (r.rule_id) byRule[r.rule_id] = r.n; + + return { + window_ms: windowMs, + window_start: windowStart, + window_end: windowEnd, + emits_in_window: emitsRow?.cnt ?? 0, + rule_matched_in_window: ruleMatchedRow?.cnt ?? 0, + confidence: { + samples: confRow?.n ?? 0, + mean: confRow?.mean ?? null, + min: confRow?.min_c ?? null, + max: confRow?.max_c ?? null, + }, + // The caller (HTTP handler) takes this map + the live disabled set and + // sums up hits for only those rule_ids. Keeping the split here — DB + // side can't see the live engine state — means the query stays pure. + emits_by_rule: byRule, + }; +} diff --git a/src/core/analytics-store.js b/src/core/analytics-store.js index e03ed98..8a58207 100644 --- a/src/core/analytics-store.js +++ b/src/core/analytics-store.js @@ -12,7 +12,7 @@ import { existsSync, readdirSync } from 'node:fs'; import { join, dirname } from 'node:path'; import { mkdirSync } from 'node:fs'; import { readEventLog } from './session-events.js'; -import { classifySession, computeCollateral } from './window-classifier.js'; +import { classifySession, computeCollateral, buildEmitIndex, classifyFixAdoption } from './window-classifier.js'; let _Database = null; function getDatabase() { @@ -26,7 +26,7 @@ function getDatabase() { return _Database; } -const SCHEMA_VERSION = 1; +const SCHEMA_VERSION = 6; const SCHEMA_SQL = ` CREATE TABLE IF NOT EXISTS meta ( @@ -54,6 +54,7 @@ const SCHEMA_SQL = ` severity TEXT, ts TEXT NOT NULL, hint_rule_id TEXT, + hint_md_hash TEXT, content_hash TEXT, suppressed INTEGER DEFAULT 0, confidence REAL @@ -62,6 +63,10 @@ const SCHEMA_SQL = ` CREATE INDEX IF NOT EXISTS idx_diag_session ON diagnostics(session_id); CREATE INDEX IF NOT EXISTS idx_diag_check ON diagnostics(check_name); CREATE INDEX IF NOT EXISTS idx_diag_file ON diagnostics(file); + -- One diagnostic row per (session, file, fp). Re-validations of the same + -- file in the same session are ignored — first emit is the canonical one. + -- See migrate_v2_to_v3 for the upgrade path on existing DBs. + CREATE UNIQUE INDEX IF NOT EXISTS idx_diag_sff ON diagnostics(session_id, file, fp); CREATE TABLE IF NOT EXISTS proposed_fixes ( fp TEXT NOT NULL, @@ -69,9 +74,11 @@ const SCHEMA_SQL = ` ts TEXT NOT NULL, range_json TEXT, new_text_hash TEXT, - kind TEXT + kind TEXT, + rule_id TEXT ); CREATE INDEX IF NOT EXISTS idx_fixes_fp ON proposed_fixes(fp); + CREATE INDEX IF NOT EXISTS idx_fixes_rule ON proposed_fixes(rule_id); CREATE TABLE IF NOT EXISTS windows ( id INTEGER PRIMARY KEY AUTOINCREMENT, @@ -81,7 +88,9 @@ const SCHEMA_SQL = ` ts_start TEXT NOT NULL, ts_end TEXT NOT NULL, content_hash_start TEXT, - content_hash_end TEXT + content_hash_end TEXT, + is_draft INTEGER DEFAULT 0, + closed_by TEXT DEFAULT 'validate' ); CREATE INDEX IF NOT EXISTS idx_windows_session ON windows(session_id); CREATE INDEX IF NOT EXISTS idx_windows_file ON windows(session_id, file); @@ -92,10 +101,15 @@ const SCHEMA_SQL = ` window_id INTEGER NOT NULL REFERENCES windows(id), outcome TEXT NOT NULL, fix_applied TEXT, - collateral_added INTEGER DEFAULT 0 + collateral_added INTEGER DEFAULT 0, + session_id TEXT, + file TEXT ); CREATE INDEX IF NOT EXISTS idx_outcomes_fp ON outcomes(fp); CREATE INDEX IF NOT EXISTS idx_outcomes_window ON outcomes(window_id); + -- One outcome per (session, file, fp). Terminal state wins via INSERT OR REPLACE. + -- See migrate_v1_to_v2 for the upgrade path on existing DBs. + CREATE UNIQUE INDEX IF NOT EXISTS idx_outcomes_sff ON outcomes(session_id, file, fp); CREATE TABLE IF NOT EXISTS rule_promotions ( rule_id TEXT PRIMARY KEY, @@ -117,7 +131,7 @@ const SCHEMA_SQL = ` CREATE INDEX IF NOT EXISTS idx_health_ts ON health_scores(ts); `; -export function openAnalyticsStore(dbPath, { readonly = false } = {}) { +export function openAnalyticsStore(dbPath, { readonly = false, blobStore = null } = {}) { if (!dbPath) throw new Error('openAnalyticsStore: dbPath required'); mkdirSync(dirname(dbPath), { recursive: true }); @@ -128,6 +142,10 @@ export function openAnalyticsStore(dbPath, { readonly = false } = {}) { db.exec('PRAGMA journal_mode = WAL'); db.exec('PRAGMA synchronous = NORMAL'); db.exec('PRAGMA foreign_keys = ON'); + // Migrations run BEFORE SCHEMA_SQL so existing tables can be reshaped + // without tripping IF-NOT-EXISTS guards (e.g. adding a UNIQUE INDEX + // over already-duplicated rows would fail if SCHEMA_SQL ran first). + migrate(db); db.exec(SCHEMA_SQL); setMeta(db, 'schema_version', String(SCHEMA_VERSION)); } @@ -167,21 +185,81 @@ export function openAnalyticsStore(dbPath, { readonly = false } = {}) { function classifyAndStoreWindows(events) { const windowResults = classifySession(events); + // Per-fp index of validator_emit events → we pull proposed_fixes off the + // latest emit in the window's time range below. Built once per session. + const emitIndex = buildEmitIndex(events); + for (const { window: w, outcomes } of windowResults) { const collateral = computeCollateral(outcomes); const windowId = insertWindow(w); + + // Resolve window content blobs once per window. classifyFixAdoption is + // a hot-ish path inside rebuilds — avoid re-reading per outcome. + const startContent = blobStore && w.content_hash_start + ? blobStore.getText(w.content_hash_start) : null; + const endContent = blobStore && w.content_hash_end + ? blobStore.getText(w.content_hash_end) : null; + for (const o of outcomes) { insertOutcome({ fp: o.fp, window_id: windowId, outcome: o.outcome, - fix_applied: null, + fix_applied: classifyOutcomeFixAdoption( + o, w, emitIndex, startContent, endContent, + ), collateral_added: o.outcome === 'regressed' ? collateral : 0, + session_id: w.session_id, + file: w.file, }); } } } + /** + * Map a window outcome to a fix_applied label ('verbatim' | 'partial' | + * 'ignored' | null). Skipped for: + * - regressed — the fp is *new* at window end, so there's no "fix that + * was proposed before and then applied"; classification is meaningless. + * - write_unverified — no end state to compare against. + * - missing content blobs — can't reconstruct start/end text. + * - no proposed fix in the window — no adoption to classify. + */ + function classifyOutcomeFixAdoption(outcome, w, emitIndex, startContent, endContent) { + if (!blobStore) return null; + if (outcome.outcome === 'regressed') return null; + if (outcome.outcome === 'write_unverified') return null; + if (!startContent || !endContent) return null; + + // Pick the emit that the agent actually saw at window start — that's the + // proposal-set the agent could have adopted. Falling back to "latest at or + // before ts_end" is wrong: it can capture a newer proposal the agent never + // saw (e.g. a rule whose `apply()` output changed between re-validations). + const emits = emitIndex.get(outcome.fp) ?? []; + let chosen = null; + for (const e of emits) { + if (e.session_id !== w.session_id) continue; + if (e.file !== w.file) continue; + if (e.ts > w.ts_start) continue; + if (!chosen || e.ts > chosen.ts) chosen = e; + } + // If no emit at or before ts_start exists, fall back to the earliest in + // the window — this covers ingestion paths where the emit and the + // tool_call share a timestamp and strict `<=` excludes the right row. + if (!chosen) { + for (const e of emits) { + if (e.session_id !== w.session_id) continue; + if (e.file !== w.file) continue; + if (e.ts > w.ts_end) continue; + if (!chosen || e.ts < chosen.ts) chosen = e; + } + } + const fixes = chosen?.proposed_fixes ?? []; + if (fixes.length === 0) return null; + + return classifyFixAdoption(startContent, endContent, fixes, blobStore); + } + function rebuild(sessionsDir) { if (!existsSync(sessionsDir)) return { sessions: 0, events: 0 }; db.exec('BEGIN'); @@ -217,14 +295,27 @@ export function openAnalyticsStore(dbPath, { readonly = false } = {}) { row.ts_start, row.ts_end, row.content_hash_start ?? null, row.content_hash_end ?? null, + row.is_draft ? 1 : 0, + row.closed_by ?? 'validate', ).lastInsertRowid; } function insertOutcome(row) { + let session_id = row.session_id ?? null; + let file = row.file ?? null; + if ((!session_id || !file) && row.window_id != null) { + const w = stmts.selectWindowById.get(row.window_id); + if (w) { + session_id = session_id || w.session_id; + file = file || w.file; + } + } stmts.insertOutcome.run( row.fp, row.window_id, row.outcome, row.fix_applied ?? null, row.collateral_added ?? 0, + session_id, + file, ); } @@ -318,20 +409,27 @@ function prepareStatements(db) { 'INSERT INTO events (session_id, kind, ts, payload) VALUES (?, ?, ?, ?)', ), insertDiag: db.prepare( - `INSERT INTO diagnostics (fp, template_fp, session_id, file, check_name, severity, ts, hint_rule_id, content_hash, suppressed, confidence) - VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + `INSERT OR IGNORE INTO diagnostics (fp, template_fp, session_id, file, check_name, severity, ts, hint_rule_id, hint_md_hash, content_hash, suppressed, confidence) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, ), insertFix: db.prepare( - `INSERT INTO proposed_fixes (fp, session_id, ts, range_json, new_text_hash, kind) - VALUES (?, ?, ?, ?, ?, ?)`, + `INSERT INTO proposed_fixes (fp, session_id, ts, range_json, new_text_hash, kind, rule_id) + VALUES (?, ?, ?, ?, ?, ?, ?)`, ), insertWindow: db.prepare( - `INSERT INTO windows (session_id, file, idx, ts_start, ts_end, content_hash_start, content_hash_end) - VALUES (?, ?, ?, ?, ?, ?, ?)`, + `INSERT INTO windows (session_id, file, idx, ts_start, ts_end, content_hash_start, content_hash_end, is_draft, closed_by) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, ), + // INSERT OR REPLACE + UNIQUE(session_id, file, fp) is the dedup mechanism: + // as classifySession walks windows chronologically, each replace stamps + // the terminal (session, file, fp) classification. insertOutcome: db.prepare( - `INSERT INTO outcomes (fp, window_id, outcome, fix_applied, collateral_added) - VALUES (?, ?, ?, ?, ?)`, + `INSERT OR REPLACE INTO outcomes + (fp, window_id, outcome, fix_applied, collateral_added, session_id, file) + VALUES (?, ?, ?, ?, ?, ?, ?)`, + ), + selectWindowById: db.prepare( + `SELECT session_id, file FROM windows WHERE id = ?`, ), insertPromotion: db.prepare( `INSERT OR REPLACE INTO rule_promotions (rule_id, check_name, template_fp, promoted_at, probation, resolved_at, resolution) @@ -354,6 +452,7 @@ function ingestValidatorEmit(event, stmts) { null, event.ts, event.hint_rule_id ?? null, + event.hint_md_hash ?? null, event.content_hash ?? null, 0, event.confidence ?? null, @@ -368,6 +467,7 @@ function ingestValidatorEmit(event, stmts) { fix.range ? JSON.stringify(fix.range) : null, fix.new_text_hash ?? null, fix.kind ?? null, + fix.rule_id ?? null, ); } } @@ -376,3 +476,148 @@ function ingestValidatorEmit(event, stmts) { function setMeta(db, key, value) { db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)').run(key, value); } + +/** + * Schema migrations. Called before SCHEMA_SQL so existing tables can be + * reshaped (e.g. adding columns, dedup, adding UNIQUE INDEX) without the + * CREATE … IF NOT EXISTS guards masking stale shape. + * + * New DBs skip migrations — meta.schema_version is absent (treated as 0) but + * the tables SCHEMA_SQL creates already match SCHEMA_VERSION. A fresh DB + * hits migrate_v1_to_v2 as a no-op because the outcomes table doesn't + * exist yet. Safe. + */ +function migrate(db) { + // Meta table must exist before we can read schema_version. + db.exec(`CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)`); + const row = db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version'); + const current = row ? Number(row.value) : 0; + + if (current < 2) migrate_v1_to_v2(db); + if (current < 3) migrate_v2_to_v3(db); + if (current < 4) migrate_v3_to_v4(db); + if (current < 5) migrate_v4_to_v5(db); + if (current < 6) migrate_v5_to_v6(db); +} + +function migrate_v1_to_v2(db) { + // No-op for fresh DBs: the outcomes table doesn't exist yet. + const outcomesExists = db.prepare( + `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'outcomes'`, + ).get(); + if (!outcomesExists) return; + + const cols = db.prepare(`PRAGMA table_info(outcomes)`).all().map(r => r.name); + if (!cols.includes('session_id')) { + db.exec(`ALTER TABLE outcomes ADD COLUMN session_id TEXT`); + } + if (!cols.includes('file')) { + db.exec(`ALTER TABLE outcomes ADD COLUMN file TEXT`); + } + + // Backfill from windows via window_id. Correlated subquery works across all + // SQLite versions (UPDATE FROM requires 3.33+). + db.exec(` + UPDATE outcomes + SET + session_id = COALESCE(session_id, (SELECT w.session_id FROM windows w WHERE w.id = outcomes.window_id)), + file = COALESCE(file, (SELECT w.file FROM windows w WHERE w.id = outcomes.window_id)) + WHERE session_id IS NULL OR file IS NULL + `); + + // Dedup: keep the highest-id row per (session_id, file, fp). classifySession + // walks windows chronologically, so the highest id is the terminal state. + // Rows with NULL session_id or file are orphans (missing window); drop them. + db.exec(` + DELETE FROM outcomes + WHERE session_id IS NULL OR file IS NULL + `); + db.exec(` + DELETE FROM outcomes + WHERE id NOT IN ( + SELECT MAX(id) FROM outcomes + GROUP BY session_id, file, fp + ) + `); + + // UNIQUE INDEX goes up after dedup; SCHEMA_SQL's IF-NOT-EXISTS guard then + // becomes a no-op on the next open. + db.exec(` + CREATE UNIQUE INDEX IF NOT EXISTS idx_outcomes_sff + ON outcomes(session_id, file, fp) + `); +} + +function migrate_v2_to_v3(db) { + // No-op for fresh DBs: the diagnostics table doesn't exist yet. + const diagExists = db.prepare( + `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'diagnostics'`, + ).get(); + if (!diagExists) return; + + // Dedup: keep the earliest row per (session_id, file, fp). The first emit + // is canonical; later re-validations of the same file in the same session + // carry the same diagnostic and add no new information. + db.exec(` + DELETE FROM diagnostics + WHERE rowid NOT IN ( + SELECT MIN(rowid) FROM diagnostics + GROUP BY session_id, file, fp + ) + `); + + db.exec(` + CREATE UNIQUE INDEX IF NOT EXISTS idx_diag_sff + ON diagnostics(session_id, file, fp) + `); +} + +function migrate_v3_to_v4(db) { + // No-op for fresh DBs: windows table doesn't exist yet (created by SCHEMA_SQL). + const windowsExists = db.prepare( + `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'windows'`, + ).get(); + if (!windowsExists) return; + + const cols = db.prepare('PRAGMA table_info(windows)').all().map(c => c.name); + if (!cols.includes('is_draft')) { + db.exec('ALTER TABLE windows ADD COLUMN is_draft INTEGER DEFAULT 0'); + } + if (!cols.includes('closed_by')) { + db.exec("ALTER TABLE windows ADD COLUMN closed_by TEXT DEFAULT 'validate'"); + } +} + +function migrate_v4_to_v5(db) { + // No-op for fresh DBs: diagnostics table doesn't exist yet. + const diagExists = db.prepare( + `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'diagnostics'`, + ).get(); + if (!diagExists) return; + + const cols = db.prepare('PRAGMA table_info(diagnostics)').all().map(c => c.name); + if (!cols.includes('hint_md_hash')) { + db.exec('ALTER TABLE diagnostics ADD COLUMN hint_md_hash TEXT'); + } + // No backfill: the event log still carries `hint_md_hash` in each + // validator_emit payload — a subsequent store.rebuild(sessionsDir) replays + // it correctly into the new column. Migration alone just unblocks future + // writes; operators that want historical hints must run a rebuild. +} + +function migrate_v5_to_v6(db) { + // No-op for fresh DBs: proposed_fixes table doesn't exist yet. + const tblExists = db.prepare( + `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'proposed_fixes'`, + ).get(); + if (!tblExists) return; + + const cols = db.prepare('PRAGMA table_info(proposed_fixes)').all().map(c => c.name); + if (!cols.includes('rule_id')) { + db.exec('ALTER TABLE proposed_fixes ADD COLUMN rule_id TEXT'); + } + db.exec('CREATE INDEX IF NOT EXISTS idx_fixes_rule ON proposed_fixes(rule_id)'); + // Existing rows stay at NULL rule_id (pre-I1 events don't carry attribution). + // A store.rebuild(sessionsDir) backfills from newer events; older events are + // genuinely un-attributed and will remain that way. +} diff --git a/src/core/case-base.js b/src/core/case-base.js index c81347c..131e5d2 100644 --- a/src/core/case-base.js +++ b/src/core/case-base.js @@ -47,7 +47,7 @@ export function retrieveCases(store, check, templateFp, { minCases = MIN_CASES } const outcomeRows = store.query(` SELECT o.outcome, o.fix_applied, o.collateral_added, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp + JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.check_name = ? AND d.template_fp = ? GROUP BY o.outcome, o.fix_applied ORDER BY cnt DESC @@ -101,10 +101,18 @@ export function retrieveCasesByCheck(store, check, { minCases = MIN_CASES, limit } /** - * F2: Per-rule rolling stats. + * F2: Per-rule rolling stats — **promotion-gating view.** * - * For each rule_id, compute (emitted, adopted, resolved, regressed) from - * the diagnostics + outcomes tables. + * Drives `syncDisabledRules` and probation resolution. Default threshold is 5 + * because promotion decisions must be statistically meaningful — one bad + * resolution on a rule that has only fired twice is not evidence to disable it. + * Reporting views that want to list every rule regardless of sample size use + * `rulePerformance()` in analytics-queries.js (threshold 1, no `disabled` flag). + * + * `${check}.unmatched` fallback rule_ids (set by the diagnostic pipeline for + * rule-less diagnostics — A4) are excluded here: they don't correspond to a + * registered rule, so "disabling" them has no effect and they shouldn't count + * toward promotion/probation decisions. * * @param {object} store * @param {object} [opts] @@ -114,12 +122,15 @@ export function retrieveCasesByCheck(store, check, { minCases = MIN_CASES, limit export function ruleScores(store, { minEmitted = 5 } = {}) { const ruleRows = store.query(` SELECT d.hint_rule_id as rule_id, - COUNT(DISTINCT d.fp) as emitted, + COUNT(*) as emitted, d.check_name as check_name FROM diagnostics d - WHERE d.hint_rule_id IS NOT NULL AND d.hint_rule_id != 'unknown' AND d.suppressed = 0 + WHERE d.hint_rule_id IS NOT NULL + AND d.hint_rule_id != 'unknown' + AND d.hint_rule_id NOT LIKE '%.unmatched' + AND d.suppressed = 0 GROUP BY d.hint_rule_id - HAVING COUNT(DISTINCT d.fp) >= ? + HAVING COUNT(*) >= ? `, [minEmitted]); const scores = []; @@ -128,8 +139,10 @@ export function ruleScores(store, { minEmitted = 5 } = {}) { const outcomeRows = store.query(` SELECT o.outcome, o.fix_applied, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp - WHERE d.hint_rule_id = ? + WHERE o.fp IN ( + SELECT DISTINCT fp FROM diagnostics + WHERE hint_rule_id = ? AND suppressed = 0 + ) GROUP BY o.outcome, o.fix_applied `, [row.rule_id]); @@ -195,7 +208,7 @@ export function scoreRule(store, ruleId, templateFp) { const outcomes = store.query(` SELECT o.outcome, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp + JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.hint_rule_id = ? AND d.template_fp = ? GROUP BY o.outcome `, [ruleId, templateFp]); @@ -253,7 +266,7 @@ export function suggestedRules(store, existingRuleChecks = new Set(), { minCases const outcomeRows = store.query(` SELECT o.outcome, o.fix_applied, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp + JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.check_name = ? AND d.template_fp = ? GROUP BY o.outcome, o.fix_applied `, [c.check_name, c.template_fp]); @@ -452,7 +465,7 @@ export function resolveProbation(store, { minOutcomes = 20 } = {}) { const outcomeRows = store.query(` SELECT o.outcome, COUNT(*) as cnt FROM outcomes o - JOIN diagnostics d ON o.fp = d.fp + JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file WHERE d.hint_rule_id = ? GROUP BY o.outcome `, [promo.rule_id]); diff --git a/src/core/constants.js b/src/core/constants.js index ea8419f..0531a3d 100644 --- a/src/core/constants.js +++ b/src/core/constants.js @@ -36,6 +36,33 @@ export const FILTER_MATCH_MAX_DISTANCE = 2; /** After this many consecutive non-decreasing error counts, warn the agent. */ export const CONSECUTIVE_ERROR_THRESHOLD = 3; +// ── Confidence defaults ───────────────────────────────────────────────────── + +/** + * Default confidence for a diagnostic when the rule engine did not set one. + * + * These are coarse priors: errors are high-confidence (the linter is usually + * right about real bugs), warnings are mid-confidence (more stylistic / context + * dependent), infos are low-confidence (advisory). + * + * A populated confidence — even a default — lets confidenceCalibration bucket + * every diagnostic instead of silently dropping ones where no rule matched. + * Case-base scoring can still override for rule-matched diagnostics. + */ +export const DEFAULT_CONFIDENCE_BY_SEVERITY = { + error: 0.9, + warning: 0.7, + info: 0.5, +}; + +/** + * Default confidence for pos-supervisor structural warnings (check names + * prefixed with `pos-supervisor:`). These are AST-derived, not LSP-derived, + * and are more deterministic than severity alone suggests — they only fire + * when the structural rule is actually hit. + */ +export const STRUCTURAL_DEFAULT_CONFIDENCE = 0.75; + // ── Limits ────────────────────────────────────────────────────────────────── /** Max subprocess output buffer (pos-cli check). */ diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js index f2524bf..9a41407 100644 --- a/src/core/diagnostic-pipeline.js +++ b/src/core/diagnostic-pipeline.js @@ -28,6 +28,15 @@ * 15. verifyOrphanedPartialOnDisk — independent (filesystem check) — must run AFTER 8 * so pending-plan suppression runs first; this catches the post-write case where * the files ARE on disk but the checker hasn't re-indexed (scaffold write:true). + * 16. verifyMissingPartialsOnDisk — independent (filesystem check) — must run AFTER 9 + * so pending suppression handles in-plan partials first; the disk check then + * catches partials that ARE on disk but the LSP hasn't re-indexed yet. + * 17. populateDefaultConfidence — must run LAST (after all suppressions/verifications) + * so it only stamps diagnostics that actually survive to the agent. The rule + * engine sets confidence and rule_id when a rule matches; this step covers + * everything else with a severity-based default confidence and a stable + * `${check}.unmatched` rule_id fallback (A4) so confidenceCalibration can bucket + * every row and the Rule Performance table attributes every emit to some rule. * * NOTE: MissingPartial, MissingPage and TranslationKeyExists are real errors — do NOT downgrade * them based on isPreWrite or other implicit state. Use pending_files / pending_pages / @@ -42,6 +51,7 @@ import { getKnownModulesMissingDocs } from './knowledge-loader.js'; import { buildAssetIndex, resolveAssetPath } from './asset-index.js'; import { buildTranslationIndex } from './translation-index.js'; import { buildPageRouteIndex, parseMissingPageMessage, resolvePageRoute } from './page-route-index.js'; +import { DEFAULT_CONFIDENCE_BY_SEVERITY, STRUCTURAL_DEFAULT_CONFIDENCE } from './constants.js'; /** * Run the full diagnostic post-processing pipeline. @@ -188,6 +198,16 @@ export function runDiagnosticPipeline(result, opts) { traceStep('verifyOrphanedPartialOnDisk', () => verifyOrphanedPartialOnDisk(result, filePath, projectDir)); } + // 16. Verify MissingPartial against filesystem + if (projectDir) { + traceStep('verifyMissingPartialsOnDisk', () => verifyMissingPartialsOnDisk(result, projectDir)); + } + + // 17. Stamp a default confidence on every surviving diagnostic that the rule + // engine did not already score. Runs last so suppressed/downgraded items + // are gone by now. + traceStep('populateDefaultConfidence', () => populateDefaultConfidence(result)); + // Attach pipeline trace for dashboard inspector (D2) result._pipelineTrace = trace; } @@ -886,11 +906,108 @@ function verifyOrphanedPartialOnDisk(result, filePath, projectDir) { }); } +/** + * Cross-check every MissingPartial against the real filesystem. + * + * The LSP's partial index lags behind disk writes. A partial written during a + * scaffold step produces a false-positive MissingPartial until the LSP re-indexes. + * Module partials (names starting with 'modules/') are skipped — they are not local + * disk files and cannot be suppressed by presence checks. + */ +function verifyMissingPartialsOnDisk(result, projectDir) { + const candidates = [...result.errors, ...result.warnings].filter(d => d.check === 'MissingPartial'); + if (candidates.length === 0) return; + + const suppressed = new Set(); + const verified = []; + + for (const d of candidates) { + const nameMatch = d.message?.match(/['"]([^'"]+)['"]/); + if (!nameMatch) continue; + const name = nameMatch[1]; + if (name.startsWith('modules/')) continue; + + if (resolveMissingPartialPaths(name, projectDir).some(p => existsSync(p))) { + suppressed.add(d); + verified.push(name); + } + } + + if (suppressed.size === 0) return; + + result.errors = result.errors.filter(d => !suppressed.has(d)); + result.warnings = result.warnings.filter(d => !suppressed.has(d)); + result.infos.push({ + check: 'pos-supervisor:MissingPartialSuppressed', + severity: 'info', + message: `Suppressed ${verified.length} MissingPartial diagnostic(s) — partial(s) exist on disk: ${verified.join(', ')}. (LSP cache lag — partial was written but not yet re-indexed.)`, + }); +} + +function resolveMissingPartialPaths(name, projectDir) { + if (/(?:^|\/)commands\//.test(name) || /(?:^|\/)queries\//.test(name)) { + const stripped = name.replace(/^lib\//, ''); + return [join(projectDir, 'app', 'lib', `${stripped}.liquid`)]; + } + return [ + join(projectDir, 'app', 'views', 'partials', `${name}.liquid`), + join(projectDir, 'app', 'views', 'partials', `${name}.html.liquid`), + ]; +} + function extractPartialNameFromPath(filePath) { const m = filePath.match(/^app\/views\/partials\/(.+?)\.(?:html\.)?liquid$/); return m ? m[1] : null; } +function defaultConfidenceFor(diag) { + if (typeof diag.check === 'string' && diag.check.startsWith('pos-supervisor:')) { + return STRUCTURAL_DEFAULT_CONFIDENCE; + } + const sev = diag.severity; + if (sev && DEFAULT_CONFIDENCE_BY_SEVERITY[sev] != null) { + return DEFAULT_CONFIDENCE_BY_SEVERITY[sev]; + } + return DEFAULT_CONFIDENCE_BY_SEVERITY.warning; +} + +function defaultRuleIdFor(diag) { + // Stable fallback so rule-less diagnostics cluster under a single bucket per + // check instead of scattering into `unknown` or the check name alone (which + // collides with the check-level scorecard and muddles rule attribution). + // See A4 in docs/new-task/implementation-plan.md. + return diag.check ? `${diag.check}.unmatched` : 'unknown.unmatched'; +} + +function populateDefaultConfidence(result) { + const stamp = (d) => { + if (d.confidence == null) d.confidence = defaultConfidenceFor(d); + if (!d.rule_id) d.rule_id = defaultRuleIdFor(d); + }; + for (const d of result.errors) stamp(d); + for (const d of result.warnings) stamp(d); + for (const d of result.infos) stamp(d); +} + +/** + * Stand-alone entry point — same semantics as the pipeline's step 17, callable + * from outside the pipeline. + * + * Reason it exists: `validate-code.js` pushes several diagnostic sources + * (structural warnings, schema validation, translation YAML check, diff-aware + * RemovedRender/RemovedGraphQL/AddedParam, new-partial caller check) into + * `result.errors` / `result.warnings` AFTER `runDiagnosticPipeline` finishes. + * Those late additions would otherwise escape `populateDefaultConfidence` and + * land in the analytics store with `confidence = null` / `rule_id` missing. + * See the confidence-stamp bug identified in the 2026-04-23 DEMO report. + * + * Idempotent — calling twice is safe because the helper only fills when + * fields are null/missing. + */ +export function stampDefaultsOn(result) { + populateDefaultConfidence(result); +} + function hasRenderReferenceOnDisk(projectDir, partialName, selfPath) { const escaped = partialName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); const pattern = new RegExp(`['"]${escaped}['"]`); diff --git a/src/core/error-enricher.js b/src/core/error-enricher.js index b17428f..02b6ee2 100644 --- a/src/core/error-enricher.js +++ b/src/core/error-enricher.js @@ -538,3 +538,62 @@ export async function enrichAll(diagnostics, ctx) { return Promise.all(diagnostics.map(d => enrichError(d, { ...ctx, _hoverCache: hoverCache }))); } + +/** + * Bridge rule-engine attribution onto diagnostics that didn't pass through + * `enrichAll` — structural warnings, schema/translation/GraphQL validators, + * diff-aware RemovedRender/AddedParam, new-partial caller check. Those are + * pushed into `result.errors/warnings` AFTER `enrichAll` returns, so their + * rule modules never fire and they land in analytics as `.unmatched`. + * + * This helper runs `runRules` on any diagnostic whose `rule_id` is still + * unset and whose `check` has a registered rule module. On a match it copies + * the rule's `rule_id`, `hint_md`, `confidence`, `see_also`, `fixes`, and + * `case_base_signal` onto the diagnostic — same fields the main enrichAll + * path writes, so downstream (emit loop, fix generator, dashboard) treats + * the diagnostic identically to one that went through enrichAll. + * + * Idempotent: diagnostics already carrying a `rule_id` are skipped so this + * can safely run after enrichAll + structural-warnings push without double + * scoring. + */ +export function bridgeRulesOntoUnattributed(result, ctx) { + const { filePath, content, factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore } = ctx; + if (!factGraph) return; + + const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore }; + + const apply = (d) => { + if (d.rule_id) return; // already attributed + if (!d.check) return; + if (!hasRules(d.check)) return; + + const params = extractParams(d.check, d.message); + const tmplFp = templateOf(d.check, d.message); + const diag = { + check: d.check, + params, + message: d.message, + file: filePath, + line: d.line, + column: d.column ?? 0, + template_fp: tmplFp, + }; + let ruleResult; + try { ruleResult = runRules(diag, facts); } + catch { return; } // runRules failure is non-fatal + if (!ruleResult) return; + + d.rule_id = ruleResult.rule_id; + if (ruleResult.hint_md && !d.hint) d.hint = ruleResult.hint_md; + if (ruleResult.confidence != null && d.confidence == null) d.confidence = ruleResult.confidence; + if (ruleResult.see_also && !d.see_also) d.see_also = ruleResult.see_also; + if (ruleResult.case_base_signal && !d.case_base_signal) d.case_base_signal = ruleResult.case_base_signal; + if (ruleResult.fixes?.length > 0 && !d.fixes) d.fixes = ruleResult.fixes; + attachSeeAlso(d, content); + }; + + for (const d of result.errors) apply(d); + for (const d of result.warnings) apply(d); + for (const d of result.infos) apply(d); +} diff --git a/src/core/fix-generator.js b/src/core/fix-generator.js index be626de..be73fa3 100644 --- a/src/core/fix-generator.js +++ b/src/core/fix-generator.js @@ -1314,10 +1314,18 @@ export function generateFixes(diagnostics, ast, content, filePath, ctx, projectD if (!fix) continue; + // I1 — rule attribution for heuristic fixes. Tagging once here keeps every + // per-check branch above free of boilerplate. The emit loop propagates this + // into the proposed_fixes.rule_id column so Rule Performance can attribute + // adoption to a specific heuristic variant (heuristic:.). + if (!fix.rule_id) { + fix.rule_id = `heuristic:${d.check ?? 'Unknown'}.${fix.type ?? 'fix'}`; + } + if (fix.type === 'add_doc_param') { docParamFixes.push({ index: i, ...fix }); // Attach per-diagnostic fix reference - diagnosticFixes.set(i, { type: 'add_doc_param', description: fix.description, param_name: fix.param_name }); + diagnosticFixes.set(i, { type: 'add_doc_param', description: fix.description, param_name: fix.param_name, rule_id: fix.rule_id }); } else { diagnosticFixes.set(i, fix); // Deduplicate: don't add identical fixes diff --git a/src/core/fs-watcher.js b/src/core/fs-watcher.js index d09a3f3..f1d4453 100644 --- a/src/core/fs-watcher.js +++ b/src/core/fs-watcher.js @@ -283,7 +283,7 @@ async function resyncFile(absPath, lsp, log, emit, counters, hooks = {}) { // Also send workspace/didChangeWatchedFiles — LSPs that honor this spec // method take it as a hint to re-scan. Harmless on LSPs that do not. notifyDidChangeWatched(lsp, uri, 2 /* Changed */, log, counters); - emit('fs_watcher_sync', { path: absPath }); + emit('fs_watcher_sync', { path: absPath, rel_path: relPath }); } } catch (e) { counters.errors++; diff --git a/src/core/rule-overrides.js b/src/core/rule-overrides.js new file mode 100644 index 0000000..f6f65ad --- /dev/null +++ b/src/core/rule-overrides.js @@ -0,0 +1,126 @@ +/** + * Rule overrides — manual force-enable / force-disable records that survive + * restart. Persisted at `/.pos-supervisor/rule-overrides.json`. + * + * Two kinds of override: + * - force_enable: rule runs even when case-base scoring would disable it. + * Use case: operator wants to re-test a rule after fixing + * a false-positive source, before enough fresh outcomes + * accumulate to auto-flip the score. + * - force_disable: rule never runs, even if the engine considers it healthy. + * Use case: emergency kill-switch for a rule producing bad + * suggestions in production. + * + * File schema (JSON): + * { + * "version": 1, + * "force_enable": { "": { "ts": "", "reason": "" } }, + * "force_disable": { "": { "ts": "", "reason": "" } } + * } + * + * Reads are tolerant: a missing file → empty overrides. A malformed file is + * logged (via the caller's log hook) and treated as empty, never thrown — + * the dashboard must stay reachable even if someone hand-edited the JSON. + * Writes are atomic (temp + rename) so a crash mid-save can't leave the file + * half-written. + */ + +import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; + +const FILE_VERSION = 1; +const FILE_NAME = 'rule-overrides.json'; + +function overridesPath(projectDir) { + return join(projectDir, '.pos-supervisor', FILE_NAME); +} + +function emptyState() { + return { version: FILE_VERSION, force_enable: {}, force_disable: {} }; +} + +/** + * Load overrides from disk. Never throws — on any error returns empty state + * and calls `log` if provided. Intentional: a corrupt overrides file must + * not prevent the server from starting. + */ +export function loadOverrides(projectDir, { log } = {}) { + const path = overridesPath(projectDir); + if (!existsSync(path)) return emptyState(); + try { + const raw = readFileSync(path, 'utf-8'); + const parsed = JSON.parse(raw); + const fe = parsed?.force_enable ?? {}; + const fd = parsed?.force_disable ?? {}; + if (typeof fe !== 'object' || typeof fd !== 'object') { + throw new Error('force_enable / force_disable must be objects'); + } + return { version: FILE_VERSION, force_enable: { ...fe }, force_disable: { ...fd } }; + } catch (e) { + log?.(`rule-overrides: failed to parse ${path} (${e.message}); treating as empty`); + return emptyState(); + } +} + +/** + * Atomic write: stage to a sibling temp file, then rename. fs rename within + * the same dir is atomic on POSIX. A reader during the write sees either the + * old file or the new — never a torn read. + */ +export function saveOverrides(projectDir, state, { log } = {}) { + const path = overridesPath(projectDir); + mkdirSync(dirname(path), { recursive: true }); + const payload = JSON.stringify({ + version: FILE_VERSION, + force_enable: state.force_enable ?? {}, + force_disable: state.force_disable ?? {}, + }, null, 2); + const tmp = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`; + try { + writeFileSync(tmp, payload); + renameSync(tmp, path); + } catch (e) { + log?.(`rule-overrides: save failed (${e.message})`); + throw e; + } +} + +/** + * Register a force-enable for `ruleId`. Removes any force-disable for the + * same rule (the two are mutually exclusive — setting one clears the other). + * Persists immediately. + */ +export function addForceEnable(projectDir, ruleId, reason = '', { log } = {}) { + if (!ruleId) throw new Error('addForceEnable: ruleId required'); + const state = loadOverrides(projectDir, { log }); + state.force_enable[ruleId] = { ts: new Date().toISOString(), reason }; + delete state.force_disable[ruleId]; + saveOverrides(projectDir, state, { log }); + return state; +} + +export function addForceDisable(projectDir, ruleId, reason = '', { log } = {}) { + if (!ruleId) throw new Error('addForceDisable: ruleId required'); + const state = loadOverrides(projectDir, { log }); + state.force_disable[ruleId] = { ts: new Date().toISOString(), reason }; + delete state.force_enable[ruleId]; + saveOverrides(projectDir, state, { log }); + return state; +} + +export function removeOverride(projectDir, ruleId, { log } = {}) { + if (!ruleId) throw new Error('removeOverride: ruleId required'); + const state = loadOverrides(projectDir, { log }); + delete state.force_enable[ruleId]; + delete state.force_disable[ruleId]; + saveOverrides(projectDir, state, { log }); + return state; +} + +/** Convenience for callers that just want two string[] of rule_ids. */ +export function overrideSets(state) { + return { + force_enable: new Set(Object.keys(state.force_enable ?? {})), + force_disable: new Set(Object.keys(state.force_disable ?? {})), + }; +} diff --git a/src/core/rules/ConvertIncludeToRender.js b/src/core/rules/ConvertIncludeToRender.js new file mode 100644 index 0000000..0bd2e32 --- /dev/null +++ b/src/core/rules/ConvertIncludeToRender.js @@ -0,0 +1,30 @@ +/** + * ConvertIncludeToRender rule — migrate deprecated `{% include %}` to + * `{% render %}`. The LSP reports the check on every non-module include; this + * rule attaches the recommendation and stable attribution. A `text_edit` + * replacement (`include` → `render`) is produced by the heuristic + * fix-generator in full mode, with a guarded fallback for module-helper + * includes where the rename is NOT safe. + * + * The module-helper guard lives in fix-generator.js (pattern: `include + * 'modules/...'`). Keeping the skip logic there rather than duplicating it + * here means one source of truth — this rule just makes sure every include + * call gets a useful hint and a non-`unmatched` rule_id. + * + * Plan reference: Tier 1 trivial wins. + */ + +export const rules = [ + { + id: 'ConvertIncludeToRender.default', + check: 'ConvertIncludeToRender', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'ConvertIncludeToRender.default', + hint_md: 'Replace `{% include "partial" %}` with `{% render "partial" %}`. `render` has isolated scope — pass every variable the partial needs explicitly: `{% render "partial", var: value %}`. Exception: `include` for **module helpers** (authorization, redirects) is correct because those partials intentionally need shared scope; the heuristic fix-generator detects this and proposes guidance instead of a rename.', + fixes: [], + confidence: 0.9, + }), + }, +]; diff --git a/src/core/rules/ImgLazyLoading.js b/src/core/rules/ImgLazyLoading.js new file mode 100644 index 0000000..1fc8b65 --- /dev/null +++ b/src/core/rules/ImgLazyLoading.js @@ -0,0 +1,24 @@ +/** + * ImgLazyLoading rule — performance hint. The LSP flags an `` without + * `loading="lazy"`; this rule attaches the recommendation text and stable + * attribution. The `text_edit` insert itself is produced by the heuristic + * fix-generator in full mode — rules this trivial don't need to reimplement + * position calculation. + * + * Plan reference: Tier 1 trivial wins. + */ + +export const rules = [ + { + id: 'ImgLazyLoading.recommended', + check: 'ImgLazyLoading', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'ImgLazyLoading.recommended', + hint_md: 'Add `loading="lazy"` to this `` tag so the browser defers off-screen image loads. Improves Core Web Vitals (LCP) and reduces initial bytes transferred on long pages.', + fixes: [], + confidence: 0.9, + }), + }, +]; diff --git a/src/core/rules/ImgWidthAndHeight.js b/src/core/rules/ImgWidthAndHeight.js new file mode 100644 index 0000000..3a5f631 --- /dev/null +++ b/src/core/rules/ImgWidthAndHeight.js @@ -0,0 +1,24 @@ +/** + * ImgWidthAndHeight rule — layout-shift hint. The LSP flags an `` without + * explicit `width` and/or `height`; this rule attaches guidance and stable + * attribution. The `text_edit` insert is produced by the heuristic + * fix-generator (full mode); the rule keeps quick-mode diagnostics usefully + * labelled. + * + * Plan reference: Tier 1 trivial wins. + */ + +export const rules = [ + { + id: 'ImgWidthAndHeight.recommended', + check: 'ImgWidthAndHeight', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'ImgWidthAndHeight.recommended', + hint_md: 'Add explicit `width` and `height` attributes to this `` tag. The browser uses them to reserve space before the image loads, eliminating cumulative layout shift (CLS). For responsive images, set the attributes to the intrinsic dimensions and override with CSS (`style="width:100%;height:auto"`).', + fixes: [], + confidence: 0.9, + }), + }, +]; diff --git a/src/core/rules/NonGetRenderingPage.js b/src/core/rules/NonGetRenderingPage.js new file mode 100644 index 0000000..f6bd6fc --- /dev/null +++ b/src/core/rules/NonGetRenderingPage.js @@ -0,0 +1,26 @@ +/** + * NonGetRenderingPage rule — attribution + hint for pages whose method is + * non-GET but whose body renders HTML. Emitted by structural-warnings.js; + * this module gives the diagnostic a stable rule_id so it lands in Rule + * Performance instead of `.unmatched`. + * + * The structural warning already produces a detailed message; the rule's + * hint_md is intentionally shorter and action-oriented (decision tree). + * No fix is proposed — the right answer depends on intent (landing page + * vs API endpoint) and guessing would do more harm than good. + */ + +export const rules = [ + { + id: 'NonGetRenderingPage.default', + check: 'pos-supervisor:NonGetRenderingPage', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'NonGetRenderingPage.default', + hint_md: 'Page will 404 on browser navigation because `method: post` only responds to POST. Decide: **landing page?** remove `method` (defaults to `get`) and have the form POST to a command handler. **API endpoint?** keep `method: post` but move the slug under `/api/…` and return JSON (not HTML). See the `NonGetRenderingPage` knowledge entry for full examples.', + fixes: [], + confidence: 0.9, + }), + }, +]; diff --git a/src/core/rules/engine.js b/src/core/rules/engine.js index d591f9f..09baf37 100644 --- a/src/core/rules/engine.js +++ b/src/core/rules/engine.js @@ -29,6 +29,15 @@ import { isAdaptive } from '../engine-mode.js'; const _registry = new Map(); const _disabledRules = new Set(); +// Operator overrides (plan I4). force_enable beats _disabledRules; force_disable +// wins over registration entirely. Both sets are the authoritative in-memory +// view — persistence is owned by rule-overrides.js and loaded/synced via +// server.js. Empty sets mean "no overrides in effect", which is the default. +const _forceEnabled = new Set(); +const _forceDisabled = new Set(); +// Per-rule metadata for dashboard display: why a rule is in _disabledRules. +// Populated by syncDisabledRules via setDisabledRuleDetails. Keyed by rule_id. +let _disabledRuleDetails = new Map(); export function registerRule(rule) { if (!rule?.id || !rule?.check || !rule?.when || !rule?.apply) { @@ -50,6 +59,19 @@ export function registerRules(rules) { for (const rule of rules) registerRule(rule); } +/** + * Decide whether a rule is active for a given call. Order: + * 1. force_disable → skip always (operator kill-switch). + * 2. force_enable → run even if case-base disabled it. + * 3. _disabledRules → skip. + * 4. otherwise → run. + */ +function ruleIsActive(ruleId) { + if (_forceDisabled.has(ruleId)) return false; + if (_forceEnabled.has(ruleId)) return true; + return !_disabledRules.has(ruleId); +} + export function runRules(diag, facts, { multiMatch = false } = {}) { const rules = _registry.get(diag.check); if (!rules || rules.length === 0) return null; @@ -57,7 +79,7 @@ export function runRules(diag, facts, { multiMatch = false } = {}) { if (multiMatch) { const results = []; for (const rule of rules) { - if (_disabledRules.has(rule.id)) continue; + if (!ruleIsActive(rule.id)) continue; try { if (rule.when(diag, facts)) { const result = rule.apply(diag, facts); @@ -72,7 +94,7 @@ export function runRules(diag, facts, { multiMatch = false } = {}) { } for (const rule of rules) { - if (_disabledRules.has(rule.id)) continue; + if (!ruleIsActive(rule.id)) continue; try { if (rule.when(diag, facts)) { const result = rule.apply(diag, facts); @@ -136,6 +158,66 @@ export function updateDisabledRules(ruleIds) { } } +/** + * Replace metadata (score, outcome counts, reason) for the disabled set. + * Consumed by the dashboard. `details` is an array of `{ rule_id, score, + * ... }` produced by `ruleScores()`; the engine stores it as-is without + * re-interpreting the fields so the shape can evolve without a schema bump. + */ +export function setDisabledRuleDetails(details) { + _disabledRuleDetails = new Map(); + if (!Array.isArray(details)) return; + for (const row of details) { + if (row?.rule_id) _disabledRuleDetails.set(row.rule_id, row); + } +} + export function getDisabledRules() { return new Set(_disabledRules); } + +/** + * Full per-rule disabled-state summary. Returns one entry per currently + * disabled rule_id with whatever metadata setDisabledRuleDetails was given. + * `force_enabled: true` means the operator has re-enabled it; it still + * appears here so the dashboard can show "disabled by analytics but running + * due to manual override". + */ +export function getDisabledRuleDetails() { + const out = []; + for (const ruleId of _disabledRules) { + const detail = _disabledRuleDetails.get(ruleId) ?? { rule_id: ruleId }; + out.push({ ...detail, force_enabled: _forceEnabled.has(ruleId) }); + } + return out; +} + +export function updateForceOverrides({ force_enable, force_disable } = {}) { + _forceEnabled.clear(); + if (force_enable) for (const id of force_enable) _forceEnabled.add(id); + _forceDisabled.clear(); + if (force_disable) for (const id of force_disable) _forceDisabled.add(id); +} + +export function getForceEnabledRules() { + return new Set(_forceEnabled); +} + +export function getForceDisabledRules() { + return new Set(_forceDisabled); +} + +/** + * True if a **check name** should be suppressed entirely (diagnostic never + * reaches the agent). Distinct from `ruleIsActive(ruleId)`, which only gates + * rule-engine registrations — this also covers structural checks + * (`pos-supervisor:*`) and LSP checks without registered rule modules. + * + * The force-disable set is a single flat namespace: it can contain either a + * rule_id (e.g. "UnknownFilter.suggest_nearest") or a bare check name + * (e.g. "pos-supervisor:HtmlInPage"). The filter in validate-code.js calls + * this with `d.check`; `runRules()` above calls the rule_id-aware path. + */ +export function isCheckForceDisabled(checkName) { + return !!checkName && _forceDisabled.has(checkName); +} diff --git a/src/core/rules/index.js b/src/core/rules/index.js index 6eb381c..ab2c8bd 100644 --- a/src/core/rules/index.js +++ b/src/core/rules/index.js @@ -17,6 +17,10 @@ import { rules as MissingRenderPartialArgumentsRules } from './MissingRenderPart import { rules as UnknownPropertyRules } from './UnknownProperty.js'; import { rules as MetadataParamsCheckRules } from './MetadataParamsCheck.js'; import { rules as GraphQLCheckRules } from './GraphQLCheck.js'; +import { rules as ImgLazyLoadingRules } from './ImgLazyLoading.js'; +import { rules as ImgWidthAndHeightRules } from './ImgWidthAndHeight.js'; +import { rules as ConvertIncludeToRenderRules } from './ConvertIncludeToRender.js'; +import { rules as NonGetRenderingPageRules } from './NonGetRenderingPage.js'; const ALL_RULE_MODULES = [ MissingPartialRules, @@ -28,6 +32,10 @@ const ALL_RULE_MODULES = [ UnknownPropertyRules, MetadataParamsCheckRules, GraphQLCheckRules, + ImgLazyLoadingRules, + ImgWidthAndHeightRules, + ConvertIncludeToRenderRules, + NonGetRenderingPageRules, ]; let _loaded = false; diff --git a/src/core/session-events.js b/src/core/session-events.js index a0dfb32..ff97e35 100644 --- a/src/core/session-events.js +++ b/src/core/session-events.js @@ -114,8 +114,17 @@ const ValidatorEmitPayload = z.object({ confidence: z.number().nullable().optional(), proposed_fixes: z.array(z.object({ range: z.unknown(), - new_text_hash: z.string(), + // Nullable because some fix types (`guidance`, `create_file`) have no + // new_text to hash. We still record that a fix was proposed so the + // dashboard sees fix-proposal rate — adoption classification skips + // these naturally (classifyFixAdoption requires a hash). + new_text_hash: z.string().nullable(), kind: z.string(), + // I1 — attribution. Rule-engine rules supply their own id + // (e.g. "UnknownFilter.suggest_nearest"); heuristic-generator fixes are + // tagged centrally as "heuristic:.". Nullable for + // back-compat with older events (pre-I1) that don't carry the field. + rule_id: z.string().nullable().optional(), })).default([]), params: z.record(z.string(), z.string()).optional(), }); diff --git a/src/core/structural-warnings.js b/src/core/structural-warnings.js index be41eec..66e638a 100644 --- a/src/core/structural-warnings.js +++ b/src/core/structural-warnings.js @@ -66,10 +66,18 @@ export function generateStructuralWarnings(ast, content, filePath, structural, e const warnings = []; const domain = getDomainFromPath(filePath); - // 1. HTML in pages — pages should be controller-only (no inline HTML) + // 1. HTML in pages — pages should be controller-only (no inline HTML). + // Guard: if the page composes partials via {% render %}, the HTML is + // usually incidental glue (landing layouts, section wrappers) rather + // than a violation. The check had 100% regression in the 2026-04-23 + // DEMO report because it fired on exactly this pattern. Suppress when + // at least one partial is rendered — the composite-page case. if (domain === 'pages') { - const htmlWarning = detectHtmlInPage(ast, content); - if (htmlWarning) warnings.push(htmlWarning); + const rendersPartials = Array.isArray(structural?.renders_used) && structural.renders_used.length > 0; + if (!rendersPartials) { + const htmlWarning = detectHtmlInPage(ast, content); + if (htmlWarning) warnings.push(htmlWarning); + } } // 2. Shopify objects in variable output not caught by linter @@ -117,6 +125,15 @@ export function generateStructuralWarnings(ast, content, filePath, structural, e if (domain === 'pages' && structural?.method) { const methodWarning = validateMethod(structural.method, content); if (methodWarning) warnings.push(methodWarning); + + // 9b. Non-GET pages don't render on browser GET requests. Agents + // sometimes set `method: post` on a landing page because they + // confuse "this page has a form that POSTs" with "this page + // itself is a POST handler". The result: the page loads blank + // because browsers do GETs. Flag the pattern when the file + // clearly renders user-facing content. + const nonGetWarning = validateNonGetRenderingPage(structural.method, structural, content); + if (nonGetWarning) warnings.push(nonGetWarning); } // 10. Front matter key validation — unknown/misleading keys, missing slug @@ -131,11 +148,12 @@ export function generateStructuralWarnings(ast, content, filePath, structural, e if (returnWarning) warnings.push(returnWarning); } - // 12. Missing {% doc %} block in commands — undocumented parameters - if (domain === 'commands') { - const docWarning = detectMissingDocBlock(content, structural, domain); - if (docWarning) warnings.push(docWarning); - } + // 12. (Removed per plan B1.5 — 2026-04-23.) + // MissingDocBlock previously also fired on commands but the production + // sample was 10% resolution / 40% regression: most internal command + // files are utility helpers or one-shot scripts with no caller-facing + // contract. Keeping the check on partials only — where a missing doc + // block is unambiguously a defect because renders need @param signals. // 13. Missing {{ content_for_layout }} in layouts — page content won't render if (domain === 'layouts') { @@ -238,17 +256,21 @@ function detectMissingContentForLayout(content) { * They should document their expected parameters. */ function detectMissingDocBlock(content, structural, domain) { + // Scoped to partials only — commands were producing a high false-positive + // rate in production (utility commands, one-shot scripts, private helpers + // with no external callers). See call site comment and plan B1.5. + if (domain !== 'partials') return null; + // Has {% doc %} block (parsed by liquid-html-parser as LiquidRawTag 'doc') if (structural?.tags_used?.includes('doc')) return null; // Has @prompt in a comment block (older convention) if (/@prompt\s*:/m.test(content)) return null; - const label = domain === 'commands' ? 'Command' : 'Partial'; return { check: 'pos-supervisor:MissingDocBlock', severity: 'warning', - message: `${label} is missing a \`{% doc %}\` block. Document expected parameters so callers know what variables to pass. Example: \`{% doc %} @param title {string} Card title {% enddoc %}\`.`, + message: `Partial is missing a \`{% doc %}\` block. Document expected parameters so callers know what variables to pass. Example: \`{% doc %} @param title {string} Card title {% enddoc %}\`.`, line: 0, column: 0, }; @@ -512,6 +534,49 @@ function validateMethod(method, content) { }; } +/** + * Flag pages whose `method` is non-GET but whose body clearly renders + * HTML / uses a layout. On platformOS these pages will not respond to + * browser navigation — GET requests get a 404. The agent's usual mistake + * pattern is `method: post` on a landing page that includes forms; the + * correct shape is `method: get` (or omit) with the form POSTing to a + * command endpoint. + * + * Intentionally permissive: if the page is clearly an API endpoint + * (returns JSON, slug under /api/, filename suggests an action), skip + * the warning. Trust the developer when the signal is strong. + */ +function validateNonGetRenderingPage(method, structural, content) { + const lower = (method || '').toLowerCase(); + if (lower === 'get' || lower === '') return null; + if (!['post', 'put', 'delete', 'patch'].includes(lower)) return null; + + const line = findFrontmatterLine(content, 'method'); + const slug = (structural?.slug || '').toLowerCase(); + + // API heuristics — skip warning if the page is clearly a backend endpoint. + const hasLayout = !!structural?.layout; + const rendersPartials = Array.isArray(structural?.renders_used) && structural.renders_used.length > 0; + const hasOutput = /\{\{/.test(content); + const hasHtmlTags = /<(html|body|div|main|section|article|form|h[1-6]|p|ul|ol|nav|header|footer)\b/i.test(content); + + // If the page has no layout, no renders, no {{ ... }} outputs, and no HTML, + // it's almost certainly a JSON/redirect endpoint. Respect that. + const looksLikeUiPage = hasLayout || rendersPartials || hasOutput || hasHtmlTags; + if (!looksLikeUiPage) return null; + + // Agent-convention API slugs: `/api/...`, `/_/…`, explicit verb suffixes. + if (/^\/?(api|_|internal)\//i.test(slug)) return null; + + return { + check: 'pos-supervisor:NonGetRenderingPage', + severity: 'warning', + message: `Page has \`method: ${lower}\` but renders HTML (layout, partials, or {{ ... }} output). Browser GETs to this URL return 404 — only ${lower.toUpperCase()} requests reach the handler. If this page should display content, remove the \`method\` field (defaults to \`get\`). If it's a form endpoint, move the handler to \`app/lib/commands/\` and have the form \`POST\` there.`, + line: line >= 0 ? line : 0, + column: 0, + }; +} + /** * Detect whether a page file is the root/index page that serves `/` by * convention — these do not need a slug in their front matter. diff --git a/src/core/window-classifier.js b/src/core/window-classifier.js index 609cdf6..4233d4a 100644 --- a/src/core/window-classifier.js +++ b/src/core/window-classifier.js @@ -147,25 +147,113 @@ export function classifyFixAdoption(startContent, endContent, proposedFixes, blo return 'partial'; } +/** + * Extract fs_watcher_sync events from the event list, grouped by relative file path. + * These represent files written to disk by the agent (via Write/Edit tools or scaffold). + * Requires fs-watcher.js to emit rel_path alongside path. + * + * @param {Array} events + * @returns {Map} file → sorted write events + */ +export function extractWriteEvents(events) { + const byFile = new Map(); + for (const event of events) { + if (event.kind !== 'fs_watcher_sync') continue; + const relPath = event.rel_path ?? null; + if (!relPath) continue; + if (!byFile.has(relPath)) byFile.set(relPath, []); + byFile.get(relPath).push(event); + } + for (const writes of byFile.values()) { + writes.sort((a, b) => (a.ts > b.ts ? 1 : a.ts < b.ts ? -1 : 0)); + } + return byFile; +} + +/** + * Classify a write-closed window: the last validation before a file write + * with no subsequent re-validation. Outcomes are 'write_unverified' because + * we know the file changed on disk but cannot determine if diagnostics were + * resolved without re-running validation. + * + * @param {object} validateCall - The last validate_code tool_call event + * @param {object} writeEvent - The fs_watcher_sync event that closed the window + * @returns {{ window, outcomes }} + */ +export function classifyWriteWindow(validateCall, writeEvent) { + const filePath = validateCall.input?.file_path ?? ''; + const startSets = buildDiagnosticSets(validateCall); + + const outcomes = startSets.diagnostics.map(diag => ({ + fp: diag.fp, + outcome: 'write_unverified', + check: diag.check, + })); + + const window = { + file: filePath, + session_id: validateCall.session_id, + ts_start: validateCall.ts, + ts_end: writeEvent.ts, + content_hash_start: extractContentHash(validateCall), + content_hash_end: null, + is_draft: false, + closed_by: 'write', + }; + + return { window, outcomes }; +} + /** * Build windows and classify outcomes for an entire session. * + * Two window kinds: + * - validate-to-validate: consecutive validate_code calls for the same file. + * Tagged is_draft=true when no fs_watcher_sync (file write) falls between them, + * meaning the agent was comparing draft iterations without writing to disk. + * - write-closed: last validate_code call followed by a file write with no + * subsequent re-validation. Outcomes are 'write_unverified'. + * * @param {Array} events - All events for a session * @param {object} [emitIndex] - Map for fix adoption lookup * @returns {Array<{window, outcomes}>} */ export function classifySession(events, emitIndex) { const byFile = extractValidateCodeCalls(events); + const writesByFile = extractWriteEvents(events); const results = []; for (const [file, calls] of byFile) { - if (calls.length < 2) continue; + const fileWrites = writesByFile.get(file) ?? []; + // ── Validate-to-validate windows ────────────────────────────────── for (let i = 0; i < calls.length - 1; i++) { - const { window, outcomes } = classifyWindow(calls[i], calls[i + 1]); + const startCall = calls[i]; + const endCall = calls[i + 1]; + const { window, outcomes } = classifyWindow(startCall, endCall); window.idx = i; + // A draft window is one where the agent iterated on content without + // writing to disk between the two validations. These measure thinking, + // not effectiveness — they should be excluded from rule scoring. + const hasMidWrite = fileWrites.some(w => w.ts > startCall.ts && w.ts <= endCall.ts); + window.is_draft = hasMidWrite ? 0 : 1; + window.closed_by = 'validate'; results.push({ window, outcomes }); } + + // ── Write-closed window ─────────────────────────────────────────── + // If a write happened after the last validation, capture it as a window. + // The agent wrote the file without re-validating, so we can't determine + // outcomes precisely — use write_unverified for all active diagnostics. + if (calls.length > 0) { + const lastCall = calls[calls.length - 1]; + const postWrite = fileWrites.find(w => w.ts > lastCall.ts); + if (postWrite) { + const { window, outcomes } = classifyWriteWindow(lastCall, postWrite); + window.idx = calls.length - 1; + results.push({ window, outcomes }); + } + } } return results; diff --git a/src/dashboard.js b/src/dashboard.js index 2ecfa0b..d65d009 100644 --- a/src/dashboard.js +++ b/src/dashboard.js @@ -698,6 +698,25 @@ export function buildDashboardHtml() { .journey-label { font-size: 8px; color: var(--muted); text-align: center; max-width: 60px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } .journey-occ { font-size: 8px; color: var(--text); font-weight: bold; } .journey-meta { margin-top: 8px; font-size: 10px; color: var(--muted); display: flex; gap: 16px; } + .journey-node.clickable { cursor: pointer; } + .journey-node.clickable:hover .journey-dot { box-shadow: 0 0 0 2px var(--blue); } + .journey-node.selected .journey-dot { box-shadow: 0 0 0 3px white; } + + /* ── Code context panel ───────────────────────────────────────────── */ + .code-ctx { margin-top: 10px; background: #1d2021; border: 1px solid var(--border); border-radius: 3px; overflow: hidden; } + .code-ctx-header { padding: 5px 10px; background: #282c2e; color: var(--muted); font-size: 10px; display: flex; justify-content: space-between; align-items: center; } + .code-ctx-pre { margin: 0; padding: 8px 10px; font-size: 10px; overflow-x: auto; line-height: 1.5; color: var(--text); } + .code-ctx-lnum { display: inline-block; min-width: 28px; text-align: right; margin-right: 8px; color: #555; user-select: none; } + .code-ctx-err-line { background: rgba(204,36,29,0.18); display: block; } + .code-ctx-fix { margin: 0; padding: 8px 10px; font-size: 10px; overflow-x: auto; line-height: 1.5; color: #b8d9a8; } + .code-ctx-fix-label { padding: 4px 10px; color: var(--green); font-size: 10px; background: rgba(142,192,124,0.12); border-top: 1px solid var(--border); } + .code-ctx-hint { margin: 0; padding: 8px 10px; font-size: 10px; overflow-x: auto; line-height: 1.5; color: #e6d4a3; white-space: pre-wrap; } + .code-ctx-hint-label { padding: 4px 10px; color: var(--yellow); font-size: 10px; background: rgba(215,153,33,0.12); border-top: 1px solid var(--border); } + .code-ctx-empty { padding: 12px; color: var(--muted); font-size: 11px; font-style: italic; } + .rd-expandable { cursor: pointer; } + .rd-expandable:hover td { background: rgba(255,255,255,0.04); } + .rd-expanded-row td { padding: 0 !important; } + .rd-expanded-row .code-ctx { margin: 0; border-radius: 0; border-left: none; border-right: none; } /* ── L3: Confidence Calibration Chart ────────────────────────────── */ .cal-container { padding: 14px; background: var(--surface); border: 1px solid var(--border); box-shadow: 2px 2px 0 var(--border); } @@ -876,6 +895,37 @@ export function buildDashboardHtml() { .sess-diff-down { color: var(--green); } .sess-diff-same { color: var(--muted); } + /* ── Adaptive Mode Impact (Part G + I4) ─────────────────────────────── */ + .ami-summary { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 8px; margin: 10px 0; } + .ami-stat { background: var(--surface); border: 1px solid var(--border); padding: 8px 10px; } + .ami-stat .n { font-size: 18px; font-weight: bold; color: var(--text); } + .ami-stat .l { font-size: 9px; text-transform: uppercase; color: var(--muted); letter-spacing: 0.5px; } + .ami-stat.delta .n { color: var(--yellow); } + .ami-section-title { margin: 12px 0 6px; font-size: 11px; font-weight: bold; text-transform: uppercase; color: var(--muted); } + .ami-section-title .muted { color: var(--muted); font-weight: normal; text-transform: none; font-size: 10px; margin-left: 6px; } + .ami-table { width: 100%; border-collapse: collapse; font-size: 10px; margin-top: 4px; } + .ami-table th { text-align: left; padding: 6px 8px; background: var(--surface); border-bottom: 1px solid var(--border); font-weight: normal; color: var(--muted); text-transform: uppercase; font-size: 9px; } + .ami-table td { padding: 5px 8px; border-bottom: 1px solid var(--border); vertical-align: top; } + .ami-table .rule-id { font-family: var(--mono); color: var(--text); } + .ami-table .reason { color: var(--muted); font-size: 9px; } + .ami-table .fe-flag { background: rgba(142,192,124,0.15); color: var(--green); padding: 1px 5px; border-radius: 2px; font-size: 9px; } + .ami-btn { font-size: 10px; padding: 2px 6px; background: none; border: 1px solid var(--border); color: var(--text); cursor: pointer; margin-right: 4px; } + .ami-btn:hover { background: rgba(255,255,255,0.06); } + .ami-btn.green { border-color: var(--green); color: var(--green); } + .ami-btn.red { border-color: var(--red); color: var(--red); } + .ami-btn[disabled] { opacity: 0.4; cursor: not-allowed; } + .ami-chip-list { display: flex; flex-wrap: wrap; gap: 6px; } + .ami-chip { background: var(--surface); border: 1px solid var(--border); padding: 3px 6px 3px 8px; font-size: 10px; display: inline-flex; align-items: center; gap: 6px; } + .ami-chip .clear-x { cursor: pointer; color: var(--muted); font-weight: bold; } + .ami-chip .clear-x:hover { color: var(--red); } + .ami-empty { color: var(--muted); font-size: 10px; font-style: italic; padding: 8px; } + .ami-legend-tiny { color: var(--muted); font-size: 9px; margin: 0 0 10px; font-style: italic; } + .ami-legend-tiny code { background: var(--surface); padding: 0 3px; border-radius: 2px; } + .ami-add-form { display: flex; gap: 6px; margin: 4px 0 4px; flex-wrap: wrap; align-items: center; } + .ami-input { background: var(--bg); border: 1px solid var(--border); color: var(--text); padding: 4px 6px; font-size: 10px; font-family: var(--mono); min-width: 280px; } + .ami-input-reason { min-width: 200px; } + .ami-input:focus { outline: none; border-color: var(--blue); } + /* ── Engine Map ────────────────────────────────────────────────────── */ .em-header { margin-bottom: 16px; } .em-title-row { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; } @@ -1479,6 +1529,41 @@ export function buildDashboardHtml() {
+ +
+
+
+ Adaptive Mode Impact + + +
+
+ What adaptive mode is doing right now vs what static mode would do. + Disabled rules are suppressed by low case-base effectiveness. Force-enable + a rule to run it anyway (e.g. to re-test after a false-positive fix); + force-disable is an emergency kill-switch. +
+
+ +
Add manual override
+
+ + + + + +
+
Autocomplete populated from rules that have ever fired. You can also type a raw check name (e.g. pos-supervisor:HtmlInPage) to suppress structural warnings that don't have a rule module.
+ +
Disabled rules
+
+
Force-enabled
+
+
Force-disabled
+
+
+
+
Rule Topology
@@ -1581,7 +1666,7 @@ const TAB_LOADERS = { insights: () => { fetchInsightsData(); if (!hintsLoaded) fetchHints(); }, analytics: () => { fetchAnalytics(); }, toollab: () => { if (!toolsLoaded) fetchTools(); fetchToolLab(); loadRuleChecks(); if (!suppressionsLoaded) fetchSuppressions(); }, - engine: () => { if (!engineMapLoaded) fetchEngineMap(); }, + engine: () => { if (!engineMapLoaded) fetchEngineMap(); fetchAdaptiveImpact(); }, 'pos-cli': () => { if (!cliEnvsLoaded) fetchCliEnvs(); }, // overview, activity, lsp: eagerly loaded via boot sequence / SSE }; @@ -1674,6 +1759,10 @@ function initSse() { // Also refresh status for stats/plan on interesting calls const important = ['validate_code','validate_intent','analyze_project','scaffold']; if (important.includes(entry.tool)) fetchStatus(); + // Keep file picker in sync with every validated file + if (entry.tool === 'validate_code' && entry.file_path) { + addToLivePickerFiles(entry.file_path); + } } else if (['lsp_ready','lsp_crash','lsp_init_failed','lsp_warmed_up'].includes(entry.event)) { fetchStatus(); renderLspLog(); @@ -1681,6 +1770,17 @@ function initSse() { syncEngineToggle(entry.mode); } else if (entry.event === 'fs_watcher_sync' || entry.event === 'fs_watcher_delete') { scheduleExplorerRefreshFromFsEvent(); + // Immediately reflect file creation/deletion in the picker without + // waiting for a full project_map refresh (which requires explorer tab open) + if (entry.path && lastStatus?.project_dir) { + const rel = entry.path.startsWith(lastStatus.project_dir + '/') + ? entry.path.slice(lastStatus.project_dir.length + 1) + : entry.path; + if (rel.startsWith('app/')) { + if (entry.event === 'fs_watcher_sync') addToLivePickerFiles(rel); + else removeFromLivePickerFiles(rel); + } + } } } catch {} }); @@ -2023,7 +2123,7 @@ async function exportSession() { var [analyticsStats, scorecards, ruleScoresData, funnelData, gapsData, engineMap, recommendations, sessionsData] = await Promise.all([ fetch(BASE + '/api/analytics/stats').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), fetch(BASE + '/api/analytics/scorecards?min_cohort=1').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), - fetch(BASE + '/api/analytics/rule-scores').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), + fetch(BASE + '/api/analytics/rule-performance').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), fetch(BASE + '/api/analytics/funnel').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), fetch(BASE + '/api/analytics/knowledge-gaps').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), fetch(BASE + '/api/engine-map').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }), @@ -2278,7 +2378,7 @@ async function exportSession() { var sortedRules = [...rules].sort(function(x, y) { return (x.effectiveness || 0) - (y.effectiveness || 0); }); for (var ri = 0; ri < sortedRules.length; ri++) { var r = sortedRules[ri]; - var rStatus = r.disabled ? 'DISABLED' : (r.effectiveness || 0) < 0.15 ? 'AT RISK' : 'OK'; + var rStatus = r.unmatched ? 'UNMATCHED' : (r.effectiveness || 0) < 0.15 ? 'AT RISK' : 'OK'; L.push('| ' + r.rule_id + ' | ' + r.emitted + ' | ' + ((r.resolution_rate || 0) * 100).toFixed(0) + '% | ' + ((r.regression_rate || 0) * 100).toFixed(0) + '% | ' + ((r.effectiveness || 0) * 100).toFixed(0) + '% | ' + rStatus + ' |'); } L.push(''); @@ -3929,6 +4029,9 @@ function renderSchemaGqlMatrix() { // ── Analytics tab ──────────────────────────────────────────────────────── let analyticsData = null; +let currentJourneyData = null; +let selectedJourneyIdx = -1; +let currentDrilldownData = null; async function fetchAnalytics() { const tsEl = document.getElementById('an-last-fetched'); @@ -3941,7 +4044,7 @@ async function fetchAnalytics() { fetch(BASE + '/api/analytics/sessions').then(r => r.ok ? r.json() : null).catch(() => null), fetch(BASE + '/api/analytics/recommendations').then(r => r.ok ? r.json() : null).catch(() => null), fetch(BASE + '/api/analytics/bigrams').then(r => r.ok ? r.json() : null).catch(() => null), - fetch(BASE + '/api/analytics/rule-scores?min_emitted=1').then(r => r.ok ? r.json() : null).catch(() => null), + fetch(BASE + '/api/analytics/rule-performance?min_emitted=1').then(r => r.ok ? r.json() : null).catch(() => null), fetch(BASE + '/api/analytics/suggested-rules').then(r => r.ok ? r.json() : null).catch(() => null), ]); @@ -4168,9 +4271,11 @@ function renderRuleScores() { + '' + s.regressed + '' + '' + s.adopted + '' + '' + effPct + '%' - + '' + (s.disabled - ? 'DISABLE' - : 'ACTIVE') + '' + + '' + (s.unmatched + ? 'UNMATCHED' + : s.effectiveness < 0.15 + ? 'AT RISK' + : 'ACTIVE') + '' + ''; }).join('') + ''; @@ -4240,6 +4345,7 @@ function closeDrilldown() { } function renderDrilldownPanel(panel, ruleId, check, drill, hint, ruleScore) { + currentDrilldownData = drill; const baseCheck = check.includes('.') ? check.split('.')[0] : check; const s = drill.samples; const outcomes = { resolved: 0, regressed: 0, unchanged: 0, moved: 0, pending: 0 }; @@ -4280,22 +4386,33 @@ function renderDrilldownPanel(panel, ruleId, check, drill, hint, ruleScore) { html += '
' + '
Recent diagnostic samples (' + total + ')
' + '' - + '' + + '' + ''; - for (const sample of s) { + for (let si = 0; si < s.length; si++) { + const sample = s[si]; const outCls = sample.outcome || 'pending'; const outLabel = sample.outcome || 'pending'; const fixLabel = sample.fix_applied === 'verbatim' ? 'verbatim' : sample.fix_applied === 'partial' ? 'partial' : sample.fix_applied ? '' + escHtml(sample.fix_applied) + '' : '--'; - const shortFile = sample.file.length > 45 ? '...' + sample.file.slice(-42) : sample.file; + const confLabel = sample.confidence != null + ? '' + (sample.confidence * 100).toFixed(0) + '%' + : 'n/a'; + const shortFile = sample.file && sample.file.length > 42 ? '...' + sample.file.slice(-39) : (sample.file || '--'); const shortSession = sample.session_id ? sample.session_id.slice(0, 8) : '--'; const ts = sample.ts ? sample.ts.replace('T', ' ').slice(0, 19) : '--'; - html += '' - + '' + const hasCtx = !!(sample.content_hash); + const expandBtn = hasCtx + ? '' + : '·'; + const expandableClass = hasCtx ? ' rd-expandable' : ''; + html += '' + + '' + + '' + '' + '' + + '' + '' + '' + '' @@ -4781,11 +4898,20 @@ function renderJourneyTimeline(el, j) { return; } + currentJourneyData = j; + selectedJourneyIdx = -1; + const nodesHtml = j.timeline.map((t, i) => { const cls = t.dominant_outcome || 'pending'; - const tip = t.session_id.slice(0, 8) + ' — ' + (t.dominant_outcome || 'no outcome') + (t.rule_id ? ' — rule: ' + t.rule_id : '') + (t.fix_applied ? ' — fix: ' + t.fix_applied : ''); + const hasCtx = !!(t.content_hash); + const tip = t.session_id.slice(0, 8) + ' — ' + (t.dominant_outcome || 'no outcome') + + (t.rule_id ? ' — rule: ' + t.rule_id : '') + + (t.fix_applied ? ' — fix: ' + t.fix_applied : '') + + (hasCtx ? ' — click to see code' : ''); const edge = i < j.timeline.length - 1 ? '
' : ''; - return '
' + const clickableClass = hasCtx ? ' clickable' : ''; + const clickAttr = hasCtx ? ' data-idx="' + i + '" onclick="selectJourneySession(' + i + ')"' : ''; + return '
' + '
' + t.occurrences + '
' + '
' + '
' + t.session_id.slice(0, 7) + '
' @@ -4793,16 +4919,160 @@ function renderJourneyTimeline(el, j) { }).join(''); el.innerHTML = '
' - + '

Journey: ' + escHtml(j.check || '?') + ' (' + escHtml(j.template_fp?.slice(0, 8) || '') + ')

' + + '

Journey: ' + escHtml(j.check || '?') + ' (' + escHtml(j.template_fp ? j.template_fp.slice(0, 8) : '') + ')

' + '
' + nodesHtml + '
' + '
' + 'SESSIONS: ' + j.session_count + '' + 'FIRST: ' + (j.first_seen || '—') + '' + 'LAST: ' + (j.last_seen || '—') + '' + '
' + + '
' + '
'; } +async function selectJourneySession(idx) { + if (!currentJourneyData) return; + const entry = currentJourneyData.timeline[idx]; + if (!entry) return; + + // Toggle deselect + if (selectedJourneyIdx === idx) { + selectedJourneyIdx = -1; + document.querySelectorAll('.journey-node.selected').forEach(function(n) { n.classList.remove('selected'); }); + const ctx = document.getElementById('journey-code-ctx'); + if (ctx) ctx.innerHTML = ''; + return; + } + + selectedJourneyIdx = idx; + document.querySelectorAll('.journey-node.selected').forEach(function(n) { n.classList.remove('selected'); }); + const nodes = document.querySelectorAll('.journey-node.clickable'); + // Find by data-idx since clickable nodes are a subset + nodes.forEach(function(n) { + if (parseInt(n.dataset.idx, 10) === idx) n.classList.add('selected'); + }); + + const ctx = document.getElementById('journey-code-ctx'); + if (!ctx) return; + await fetchAndRenderCodeCtx(ctx, entry.content_hash, entry.fix_hash, entry.fix_range, entry.file, entry.hint_md_hash); +} + +async function fetchAndRenderCodeCtx(el, contentHash, fixHash, fixRange, file, hintHash) { + el.innerHTML = '
Loading...
'; + + let content = null; + let fixText = null; + let hintText = null; + + try { + const fetches = []; + if (contentHash) { + fetches.push(fetch(BASE + '/api/blob?hash=' + encodeURIComponent(contentHash)) + .then(r => r.ok ? r.json() : null).then(d => { content = d?.text || null; })); + } + if (fixHash) { + fetches.push(fetch(BASE + '/api/blob?hash=' + encodeURIComponent(fixHash)) + .then(r => r.ok ? r.json() : null).then(d => { fixText = d?.text || null; })); + } + if (hintHash) { + fetches.push(fetch(BASE + '/api/blob?hash=' + encodeURIComponent(hintHash)) + .then(r => r.ok ? r.json() : null).then(d => { hintText = d?.text || null; })); + } + await Promise.all(fetches); + } catch (e) { + el.innerHTML = '
Error loading code context: ' + escHtml(e.message) + '
'; + return; + } + + el.innerHTML = buildCodeCtxHtml(file, content, fixText, fixRange, hintText); +} + +function buildCodeCtxHtml(file, content, fixText, fixRange, hintText) { + if (!content) { + return '
No file snapshot captured for this diagnostic.
'; + } + + var shortFile = file && file.length > 60 ? '...' + file.slice(-57) : (file || 'unknown'); + var lines = content.split('\\n'); + + // Determine highlighted line range from fix_range + var hlStart = -1, hlEnd = -1; + if (fixRange && typeof fixRange.start === 'object') { + hlStart = fixRange.start.line || 0; + hlEnd = fixRange.end ? (fixRange.end.line || hlStart) : hlStart; + } + + // Show up to 40 lines; if range is set, center on it + var totalLines = lines.length; + var windowStart = 0; + var windowSize = 40; + if (hlStart >= 0) { + windowStart = Math.max(0, hlStart - 10); + } + var windowEnd = Math.min(totalLines, windowStart + windowSize); + var shown = lines.slice(windowStart, windowEnd); + + var codeHtml = shown.map(function(line, i) { + var lineNo = windowStart + i + 1; + var isHl = hlStart >= 0 && lineNo >= hlStart + 1 && lineNo <= hlEnd + 1; + var cls = isHl ? ' class="code-ctx-err-line"' : ''; + var lnSpan = '' + lineNo + ''; + return '' + lnSpan + escHtml(line) + ''; + }).join('\\n'); + + var truncNote = (windowStart > 0 || windowEnd < totalLines) + ? ' (lines ' + (windowStart + 1) + '-' + windowEnd + ' of ' + totalLines + ')' + : ''; + + var html = '
' + + '
' + + '' + escHtml(shortFile) + truncNote + '' + + (hlStart >= 0 ? 'line ' + (hlStart + 1) + '' : '') + + '
' + + '
' + codeHtml + '
'; + + if (fixText) { + html += '
Proposed fix:
' + + '
' + escHtml(fixText) + '
'; + } + + if (hintText) { + html += '
Hint:
' + + '
' + escHtml(hintText) + '
'; + } + + html += '
'; + return html; +} + +async function toggleSampleCodeCtx(idx) { + if (!currentDrilldownData) return; + const sample = currentDrilldownData.samples[idx]; + if (!sample) return; + + const existingRow = document.getElementById('rd-ctx-row-' + idx); + if (existingRow) { + existingRow.remove(); + return; + } + + // Insert expanded row after the sample row + const sampleRow = document.getElementById('rd-sample-row-' + idx); + if (!sampleRow) return; + + const colspan = sampleRow.cells.length; + const newRow = document.createElement('tr'); + newRow.id = 'rd-ctx-row-' + idx; + newRow.className = 'rd-expanded-row'; + const td = document.createElement('td'); + td.colSpan = colspan; + td.innerHTML = '
Loading...
'; + newRow.appendChild(td); + sampleRow.insertAdjacentElement('afterend', newRow); + + await fetchAndRenderCodeCtx(td, sample.content_hash, sample.fix_hash, sample.fix_range, sample.file, sample.hint_md_hash); +} + // ── L3: Confidence Calibration Chart ──────────────────────────────────── async function fetchCalibrationChart() { const el = document.getElementById('an-calibration'); @@ -5317,23 +5587,51 @@ let currentLiveFilePath = null; let livePickerFiles = []; +function addToLivePickerFiles(path) { + if (!path || !path.startsWith('app/')) return; + if (!livePickerFiles.includes(path)) { + livePickerFiles.push(path); + livePickerFiles.sort(); + renderLivePickerOptions(); + } +} + +function removeFromLivePickerFiles(path) { + const idx = livePickerFiles.indexOf(path); + if (idx !== -1) { + livePickerFiles.splice(idx, 1); + renderLivePickerOptions(); + } +} + function populateLiveFilePicker() { const sel = document.getElementById('lc-file-picker'); - if (!sel || !explorerData) return; + if (!sel) return; const files = []; - for (const k of Object.keys(explorerData.pages || {})) files.push(explorerData.pages[k].path || k); - for (const k of Object.keys(explorerData.partials || {})) files.push(explorerData.partials[k].path || k); - for (const k of Object.keys(explorerData.layouts || {})) files.push(explorerData.layouts[k].path || k); - for (const k of Object.keys(explorerData.commands || {})) files.push(k); - for (const k of Object.keys(explorerData.queries || {})) files.push(k); - for (const k of Object.keys(explorerData.graphql || {})) files.push('app/graphql/' + k + '.graphql'); - for (const k of Object.keys(explorerData.schema || {})) { - const p = explorerData.schema[k]?.path; - if (p) files.push(p); + + if (explorerData) { + for (const k of Object.keys(explorerData.pages || {})) files.push(explorerData.pages[k].path || k); + for (const k of Object.keys(explorerData.partials || {})) files.push(explorerData.partials[k].path || k); + for (const k of Object.keys(explorerData.layouts || {})) files.push(explorerData.layouts[k].path || k); + for (const k of Object.keys(explorerData.commands || {})) files.push(k); + for (const k of Object.keys(explorerData.queries || {})) files.push(k); + for (const k of Object.keys(explorerData.graphql || {})) files.push('app/graphql/' + k + '.graphql'); + for (const k of Object.keys(explorerData.schema || {})) { + const p = explorerData.schema[k]?.path; + if (p) files.push(p); + } + for (const locale of Object.keys(explorerData.translations || {})) { + files.push('app/translations/' + locale + '.yml'); + } } - for (const locale of Object.keys(explorerData.translations || {})) { - files.push('app/translations/' + locale + '.yml'); + + // Also include every file that was validated in this session + // (covers files created after the last project_map fetch) + for (const e of [...allLogEntries, ...liveEntries]) { + if (e.event === 'tool_call' && e.tool === 'validate_code' && e.file_path) { + files.push(e.file_path); + } } livePickerFiles = [...new Set(files)].filter(f => f && f.startsWith('app/')).sort(); @@ -6215,8 +6513,187 @@ function showEmInspector(d) { document.getElementById('em-refresh-btn')?.addEventListener('click', () => { engineMapLoaded = false; fetchEngineMap(); + fetchAdaptiveImpact(); }); +// ── Adaptive Mode Impact (Part G + I4) ───────────────────────────────────── +let adaptiveImpactCache = null; + +async function fetchAdaptiveImpact() { + const tsEl = document.getElementById('ami-last-fetched'); + if (tsEl) tsEl.textContent = 'Loading...'; + + try { + // Parallel: impact summary (live engine state) + rule-performance list + // (every rule_id ever seen — powers the autocomplete datalist). + const [impactR, perfR] = await Promise.all([ + fetch(BASE + '/api/engine/impact'), + fetch(BASE + '/api/analytics/rule-performance?min_emitted=1'), + ]); + if (!impactR.ok) throw new Error('HTTP ' + impactR.status); + adaptiveImpactCache = await impactR.json(); + const perfData = perfR.ok ? await perfR.json() : { scores: [] }; + renderAdaptiveImpact(); + populateRuleIdDatalist(adaptiveImpactCache, perfData.scores ?? []); + if (tsEl) tsEl.textContent = new Date().toLocaleTimeString(); + } catch (e) { + if (tsEl) tsEl.textContent = 'Error: ' + e.message; + } +} + +// Populate the autocomplete datalist. Merges rule_ids seen in analytics +// (rulePerformance) with rule_ids currently disabled or overridden, plus +// bare check names so an entry like "pos-supervisor:HtmlInPage.unmatched" +// also suggests its check form. Sorted alphabetically. +function populateRuleIdDatalist(impact, perfScores) { + const dl = document.getElementById('ami-known-rules'); + if (!dl) return; + + const ids = new Set(); + for (const s of perfScores) if (s.rule_id) ids.add(s.rule_id); + for (const r of (impact.disabled_rules ?? [])) if (r.rule_id) ids.add(r.rule_id); + for (const r of (impact.force_enabled ?? [])) if (r) ids.add(r); + for (const r of (impact.force_disabled ?? [])) if (r) ids.add(r); + + // Also add the bare check names so "pos-supervisor:HtmlInPage" completes + // even if only its ".unmatched" variant has fired. + const checks = new Set(); + for (const id of ids) { + const base = id.replace(/\.(unmatched|recommended|default|generic|[a-z_]+)$/, ''); + if (base && base !== id) checks.add(base); + } + for (const c of checks) ids.add(c); + + const sorted = [...ids].sort(); + dl.innerHTML = sorted.map(function(id) { + return ''; + }).join(''); +} + +function renderAdaptiveImpact() { + const d = adaptiveImpactCache; + if (!d) return; + + // ── summary stats ────────────────────────────────────────────────────── + const sEl = document.getElementById('ami-summary'); + if (sEl) { + const winH = Math.round((d.window?.ms ?? 0) / 3_600_000); + const cf = d.counterfactual?.suppressed_by_disabled ?? 0; + const conf = d.confidence ?? {}; + sEl.innerHTML = [ + '
' + (d.emits_in_window ?? 0) + '
Emits (' + winH + 'h)
', + '
' + (d.rule_matched_in_window ?? 0) + '
Rule-matched
', + '
' + cf + '
Suppressed by disable
', + '
' + (conf.samples ?? 0) + '
Confidence samples
', + '
' + (conf.mean != null ? conf.mean.toFixed(2) : '—') + '
Avg confidence
', + ].join(''); + } + + // ── disabled rules table ─────────────────────────────────────────────── + const disabled = d.disabled_rules ?? []; + document.getElementById('ami-disabled-count').textContent = disabled.length ? '(' + disabled.length + ')' : '(0)'; + const tEl = document.getElementById('ami-disabled-table'); + if (disabled.length === 0) { + tEl.innerHTML = '
No rules disabled by analytics. Adaptive mode is running every registered rule.
'; + } else { + const rows = disabled.map(function(r) { + const effPct = r.effectiveness != null ? (r.effectiveness * 100).toFixed(0) + '%' : '—'; + const resPct = r.resolution_rate != null ? (r.resolution_rate * 100).toFixed(0) + '%' : '—'; + const regPct = r.regression_rate != null ? (r.regression_rate * 100).toFixed(0) + '%' : '—'; + const hits = (d.counterfactual?.per_rule_suppressed ?? {})[r.rule_id] ?? 0; + const feFlag = r.force_enabled ? 'FORCE-ENABLED' : ''; + const feBtn = r.force_enabled + ? '' + : ''; + return '
' + + '' + + '' + + '' + + '' + + '' + + '' + + ''; + }).join(''); + tEl.innerHTML = '
FileOutcomeFixCollateralSessionTimeFileOutcomeFixConfCollateralSessionTime
' + escHtml(shortFile) + '
' + expandBtn + '' + escHtml(shortFile) + '' + outLabel + '' + fixLabel + '' + confLabel + '' + (sample.collateral || '--') + '' + shortSession + '' + ts + '
' + escHtml(r.rule_id) + ' ' + feFlag + '
' + + '
' + escHtml(r.check ?? '') + ' · ' + (r.emitted ?? 0) + ' emits / ' + (r.total_outcomes ?? 0) + ' outcomes
' + effPct + '' + resPct + '' + regPct + '' + hits + '' + feBtn + '
' + + '' + + '' + rows + '
RuleEffResolvedRegressedSuppressed (window)
'; + } + + // ── force-enable / force-disable chips ──────────────────────────────── + renderAmiChipList('ami-fe-list', 'ami-fe-count', d.force_enabled ?? [], 'ami-fe-count'); + renderAmiChipList('ami-fd-list', 'ami-fd-count', d.force_disabled ?? [], 'ami-fd-count'); +} + +function renderAmiChipList(listId, countId, ids) { + const el = document.getElementById(listId); + const countEl = document.getElementById(countId); + if (countEl) countEl.textContent = ids.length ? '(' + ids.length + ')' : '(0)'; + if (!el) return; + if (ids.length === 0) { + el.innerHTML = 'None'; + return; + } + el.innerHTML = ids.map(function(id) { + return '' + escHtml(id) + + ' ✕'; + }).join(''); +} + +async function mutateOverride(ruleId, action, reason) { + try { + const r = await fetch(BASE + '/api/engine/rule-overrides', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ action, rule_id: ruleId, reason: reason ?? '' }), + }); + if (!r.ok) { + const err = await r.json().catch(function() { return { error: 'HTTP ' + r.status }; }); + alert('Override failed: ' + (err.error || r.status)); + return; + } + await fetchAdaptiveImpact(); + } catch (e) { + alert('Override failed: ' + e.message); + } +} + +function forceEnable(ruleId) { + const reason = prompt('Reason for force-enabling "' + ruleId + '" (optional):') ?? ''; + mutateOverride(ruleId, 'force_enable', reason); +} +function forceDisable(ruleId) { + const reason = prompt('Reason for force-disabling "' + ruleId + '" (optional):') ?? ''; + mutateOverride(ruleId, 'force_disable', reason); +} +function clearOverride(ruleId) { + mutateOverride(ruleId, 'clear', ''); +} + +document.getElementById('ami-refresh-btn')?.addEventListener('click', function() { fetchAdaptiveImpact(); }); + +function amiSubmitOverride(action) { + const idEl = document.getElementById('ami-add-rule-id'); + const reasonEl = document.getElementById('ami-add-reason'); + const id = (idEl?.value || '').trim(); + const reason = (reasonEl?.value || '').trim(); + if (!id) { alert('rule_id or check name required'); idEl?.focus(); return; } + mutateOverride(id, action, reason).then(function() { + if (idEl) idEl.value = ''; + if (reasonEl) reasonEl.value = ''; + }); +} +document.getElementById('ami-add-fe-btn')?.addEventListener('click', function() { amiSubmitOverride('force_enable'); }); +document.getElementById('ami-add-fd-btn')?.addEventListener('click', function() { amiSubmitOverride('force_disable'); }); + +// Two-backslash sequence is deliberate: the entire dashboard JS lives inside +// an outer template literal in buildDashboardHtml(). \\' in the source +// collapses to \' in the emitted script, which the browser then parses as a +// literal single quote inside the JS string. Using \' in the source would +// collapse to ' at template-literal parse time, breaking the emitted JS. +function escAttr(s) { + return String(s).replace(/&/g, '&').replace(/"/g, '"').replace(/'/g, "\\\\'"); +} + // ── Uptime counter ───────────────────────────────────────────────────────── setInterval(() => { if (startTime) document.getElementById('uptime').textContent = 'UP ' + fmtUptime(Date.now() - startTime); diff --git a/src/data/hints/pos-supervisor:NonGetRenderingPage.md b/src/data/hints/pos-supervisor:NonGetRenderingPage.md new file mode 100644 index 0000000..a34bdc2 --- /dev/null +++ b/src/data/hints/pos-supervisor:NonGetRenderingPage.md @@ -0,0 +1,33 @@ +A page with `method: post` (or `put`/`delete`/`patch`) only responds to that HTTP verb. Browsers navigate with GET, so this page will show **404 / not found** to real users. + +**Two common patterns and how to fix each:** + +1. **You wanted a landing page with a form.** + Remove the `method` field from the page's front matter (defaults to `get`). The form on the page should `POST` to a separate handler: + ```liquid + --- + slug: contact + layout: application + --- + + … + + ``` + Put the handler logic in `app/lib/commands/contacts/create.liquid` (or similar) and register a page under `app/views/pages/api/contacts/create.liquid` with `method: post` + a GraphQL mutation. + +2. **You wanted an API endpoint.** + Keep `method: post` but remove the HTML. The page body should be: + ```liquid + --- + slug: api/contacts/create + method: post + format: json + --- + {% graphql r = "contacts/create", input: context.params %} + {{ r | json }} + ``` + The suppressor in `pos-supervisor` recognises slugs starting with `/api/`, `/_/`, `/internal/` and won't warn in that case. + +Quick decision tree: +- Do real users visit this URL in a browser? → `method: get`. +- Is this a programmatic handler? → slug under `/api/…` and return JSON. diff --git a/src/data/resources/platformos-development-guide.md~ b/src/data/resources/ok-platformos-development-guide.md similarity index 98% rename from src/data/resources/platformos-development-guide.md~ rename to src/data/resources/ok-platformos-development-guide.md index 40929c1..a4f44b5 100644 --- a/src/data/resources/platformos-development-guide.md~ +++ b/src/data/resources/ok-platformos-development-guide.md @@ -65,6 +65,8 @@ tools will reject. 6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or `must_fix_before_write: true`, fix every error and re-validate. MUST NOT write the file to disk until validation passes. + When debugging existing files, always read them from disk first and submit + their actual content to `validat_code` tool. 7. Creation order matters: schema → graphql → partial → page. 8. **`analyze_project` — project-wide health check.** MUST be called: - **Before reporting task completion.** `validate_code` only sees one @@ -303,14 +305,17 @@ metadata: --- ``` -**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** - | Property | Default | Notes | |----------|---------|-------| | `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | | `method` | `get` | `get`, `post`, `put`, `delete` | | `layout` | `application` | Empty string for no layout | +**You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead.** +**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** +**For the home page omit method as it can only be `get` which is default.** +**One REST method per page** + ### Dynamic Routes | Pattern | URL | `context.params` | @@ -896,7 +901,7 @@ You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `po ## 14. Translations (i18n) You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. -The YAML file require top-level language key: +The YAML file requires top-level language key: ``` en: @@ -1610,7 +1615,12 @@ You MUST NOT: - Put raw GraphQL in pages (use `.graphql` files) - Create or modify application files outside the `app/` directory - Use reserved names (`id`, `created_at`, `deleted_at`, `type_name`, `properties`) as custom property/table names - +- Use more than one HTTP methods per page: +``` +#Never try to handle POST + rendering + redirect in the same root page. Keep it clean: +/ → GET → renders page +/contact (or similar) → POST → processes + redirects +``` --- ## 30. Pre-Flight Checklist diff --git a/src/data/resources/platformos-development-guide-full.md b/src/data/resources/platformos-development-guide-full.md index 4cbe916..15c9f99 100644 --- a/src/data/resources/platformos-development-guide-full.md +++ b/src/data/resources/platformos-development-guide-full.md @@ -190,7 +190,19 @@ authorization_policies:

Author: {{ context.current_user.email }}

``` -### Page Configuration Options +### Front Matter + +```liquid +--- +slug: products/:id +method: post +layout: application +metadata: + title: "Product Details" +--- +``` + +### Front Matter: Page Configuration Options | Option | Type | Description | |--------|------|-------------| @@ -201,6 +213,17 @@ authorization_policies: | `response_headers` | Hash | Custom HTTP headers | | `method` | String | HTTP method restriction | +| Property | Default | Notes | +|----------|---------|-------| +| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | +| `method` | `get` | `get`, `post`, `put`, `delete` | +| `layout` | `application` | Empty string for no layout | + +**You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead.** +**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** +**For the home page omit method as it can only be `get` which is default.** +**One REST method per page** + ### Dynamic URL Parameters ```yaml diff --git a/src/data/resources/platformos-development-guide.md b/src/data/resources/platformos-development-guide.md index 06b0485..21c47a3 100644 --- a/src/data/resources/platformos-development-guide.md +++ b/src/data/resources/platformos-development-guide.md @@ -92,6 +92,7 @@ tools will reject. `validate_code` passed on the files you edited. Individual-file green lights do not imply project integrity. + ### MUST-CALL domains (by feature type) - **Auth code** — `domain_guide(domain: "authentication")` @@ -107,11 +108,12 @@ tools will reject. `{% function %}`. - Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These do not exist in platformOS. -- Write files to disk without calling `validate_code` on the proposed content first. +- Write hand-drafted files to disk without calling `validate_code` on the proposed + content first. (Scaffold-written files are exempt — they are pre-validated.) - Assume module call syntax from memory — call `module_info(name)` to get the authoritative live-scan API surface. - Ignore `consult_before_writing` in a scaffold response. Every domain listed there - MUST be consulted via `domain_guide` before step 5. + MUST be consulted via `domain_guide` before writing. ### Session-start checklist @@ -125,8 +127,6 @@ Before your first tool call, the following are true: Proceed only when all three are checked. ---- - ## 1. Technology Stack platformOS uses three primary technologies: @@ -172,24 +172,20 @@ project-root/ │ │ ├── layouts/ # Wrapper templates │ │ └── partials/ # Reusable template snippets │ ├── lib/ -│ │ ├── commands/ # Business logic (build -> check -> execute) +│ │ ├── commands/ # Business logic (build → check → execute) │ │ ├── queries/ # Data retrieval wrappers │ │ ├── events/ # Event definitions │ │ └── consumers/ # Event handlers │ ├── schema/ # Database table definitions (YAML) │ ├── graphql/ # GraphQL query/mutation files -│ ├── forms/ # Form configurations (YAML + Liquid front matter) │ ├── emails/ # Email templates │ ├── smses/ # SMS templates │ ├── api_calls/ # Third-party API integrations │ ├── translations/ # i18n content (YAML) -│ ├── authorization_policies/ # Access control rules (page/form level) +│ ├── authorization_policies/ # DO NOT USE — use pos-module-user │ ├── migrations/ # One-time migration scripts │ └── config.yml # Feature flags ├── modules/ # Downloaded/custom modules (READ-ONLY) -│ └── MODULE_NAME/ -│ ├── public/ # Publicly accessible files -│ └── private/ # IP-protected files (not downloadable) └── .pos # Environment endpoints ``` @@ -197,42 +193,6 @@ All application files MUST reside in the `app/` directory. You MUST NOT create o The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only. -### Module Structure Details - -Modules have `public/` and `private/` subdirectories with the same internal structure: - -``` -modules/my_module/ -├── public/ -│ ├── views/ -│ ├── forms/ -│ ├── graphql/ -│ └── assets/ -└── private/ - ├── views/ - └── forms/ -``` - -- **Public files** — accessible for preview/download after deployment -- **Private files** — IP-protected, not accessible for download -- When referencing module files, omit `public/` and `private/` from the path -- Files with the same name in both directories will conflict — do not do this - -**Module file referencing:** -```liquid -{% render 'modules/my_module/header' %} -{% graphql result = 'modules/my_module/get_data' %} -{% render_form 'modules/my_module/contact_form' %} -{{ 'modules/my_module/style.css' | asset_url }} -``` - -**Module deletion behavior:** By default, module files are NOT deleted during `pos-cli deploy` to protect private files. To enable deletion: -```yaml -# app/config.yml -modules_that_allow_delete_on_deploy: - - my_module -``` - ### File Naming Conventions | Directory | Pattern | Example | @@ -263,13 +223,13 @@ Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate ### Business Logic MUST Live in Commands -All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build -> check -> execute pattern. +All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build → check → execute pattern. ### Path Resolution -- `{% render 'blog_posts/card' %}` -> `app/views/partials/blog_posts/card.liquid` -- `{% function r = 'commands/blog_posts/create' %}` -> `app/lib/commands/blog_posts/create.liquid` -- `{% function r = 'queries/blog_posts/search' %}` -> `app/lib/queries/blog_posts/search.liquid` +- `{% render 'blog_posts/card' %}` → `app/views/partials/blog_posts/card.liquid` +- `{% function r = 'commands/blog_posts/create' %}` → `app/lib/commands/blog_posts/create.liquid` +- `{% function r = 'queries/blog_posts/search' %}` → `app/lib/queries/blog_posts/search.liquid` The `lib/` prefix is implicit in `function` calls — do NOT include it. @@ -305,14 +265,17 @@ metadata: --- ``` -**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** - | Property | Default | Notes | |----------|---------|-------| | `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | | `method` | `get` | `get`, `post`, `put`, `delete` | | `layout` | `application` | Empty string for no layout | +**You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead.** +**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.** +**For the home page omit method as it can only be `get` which is default.** +**One REST method per page** + ### Dynamic Routes | Pattern | URL | `context.params` | @@ -385,7 +348,7 @@ Partials MUST NOT contain hardcoded user-facing text — always use translations Partials MUST NOT have underscore-prefixed filenames. -The render path maps: `render 'path/name'` -> `app/views/partials/path/name.liquid`. +The render path maps: `render 'path/name'` → `app/views/partials/path/name.liquid`. ### Layouts @@ -395,7 +358,7 @@ The default layout is `application`. Set `layout: ""` (empty string) in front ma ## 6. Commands (Business Logic) -All business logic MUST be encapsulated in commands following the build -> check -> execute pattern. +All business logic MUST be encapsulated in commands following the build → check → execute pattern. ### Main Command @@ -580,41 +543,6 @@ All mutations MUST alias the result as `record:` so `modules/core/commands/execu - `record: record_update(id: $id, record: { properties: [...] }) { id }` - `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table" -### Soft Delete vs Hard Delete - -**Soft delete** (default) — sets `deleted_at` timestamp: -```graphql -mutation { - record_delete(table: "article", id: "123") { - id - deleted_at # Timestamp is set - } -} -``` - -**Hard delete** (permanent) — requires `hard_delete: true`: -```graphql -mutation { - record_delete(table: "article", id: "123", hard_delete: true) { - id - } -} -``` - -Soft-deleted records can be queried using the `deleted_at` filter: -```graphql -query { - records( - filter: { - table: { value: "article" } - deleted_at: { exists: true } - } - ) { - results { id deleted_at } - } -} -``` - ### Pagination Component ```liquid @@ -641,54 +569,13 @@ properties: - name: image type: upload options: - public: true - versions: - - name: thumbnail - resize: "200x200>" - - name: medium - resize: "800x600>" + acl: public ``` ### Property Types `string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload` -### Upload Options - -| Option | Type | Description | -|--------|------|-------------| -| `public` | boolean | `true` = public URL, `false` = requires auth | -| `max_size` | integer | Max file size in bytes | -| `versions` | array | Image resize versions | -| `extensions` | array | Allowed file extensions | - -Version resize syntax: -- `100x100>` — Resize only if larger (downscale only) -- `100x100<` — Resize only if smaller (upscale only) -- `100x100#` — Exact dimensions (may crop) -- `100x100^` — Minimum dimensions (may crop) -- `100x100` — Fit within dimensions - -### Reserved Names (MUST NOT Use) - -The following names are reserved by platformOS and MUST NOT be used as custom table or property names: - -**System fields (automatically created on every record):** -- `id` — Record UUID -- `created_at` — Creation timestamp -- `updated_at` — Last update timestamp -- `deleted_at` — Soft delete timestamp -- `type_name` — Table name -- `properties` — Property container - -**Reserved table names:** -- `user`, `users` — Built-in User table -- `session`, `sessions` — Session management -- `record`, `records` — Record operations -- `constant`, `constants` — System constants -- `table`, `tables` — Table metadata -- `background_job`, `background_jobs` — Background job system - --- ## 9. Liquid Reference @@ -706,8 +593,8 @@ The following names are reserved by platformOS and MUST NOT be used as custom ta {% redirect_to '/path', status: 302 %} {% session key = value %} {% log variable, type: 'debug' %} -{% cache key: 'key_name', expire: 3600 %}...{% endcache %} -{% background source_name: 'job_name', priority: 'low', delay: 5.0, max_attempts: 3 %}...{% endbackground %} +{% cache 'key', expire: 3600 %}...{% endcache %} +{% background source_name: 'job_name', priority: 'low' %}...{% endbackground %} {% content_for_layout %} {% theme_render_rc 'modules/common-styling/toasts' %} ``` @@ -769,28 +656,13 @@ You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement M | `context.constants` | Environment constants (hidden from `{{ context }}` for security) | | `context.page.metadata` | Page metadata from front matter | -### context.current_user - -`context.current_user` is a documented platformOS object that returns basic data of the currently logged-in user: - -```liquid -{{ context.current_user.id }} # User UUID -{{ context.current_user.email }} # User email -{{ context.current_user.first_name }} # First name -{{ context.current_user.last_name }} # Last name -{{ context.current_user.slug }} # User slug -{{ context.current_user.properties }} # Custom properties hash -``` - -Returns `null` if no user is logged in. - -For projects using pos-module-user, prefer `modules/user/queries/user/current` as it provides additional normalized user data and role information. Use `context.current_user` for simple checks (e.g., checking if anyone is logged in) and the User Module query for full user data operations. +You MUST NOT use `context.current_user` directly — always use `modules/user/queries/user/current`. --- ## 11. User Module (Authentication & Authorization) -You MUST use the User Module for all authentication and authorization. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. +You MUST use the User Module for all authentication and authorization. You MUST NOT use `authorization_policies/` directly. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. ### Built-in Roles @@ -837,31 +709,6 @@ Define roles: {% return data %} ``` -### Native Authorization Policies (Optional) - -platformOS also provides `authorization_policies/` for page and form-level access control. These work independently of the User Module and are useful for simple checks: - -**File:** `app/authorization_policies/requires_login.liquid` -```liquid ---- -name: requires_login -redirect_to: /sign-in -flash_alert: Please sign in to access this page ---- -{% if context.current_user %}true{% else %}false{% endif %} -``` - -**Usage in page front matter:** -```liquid ---- -slug: admin/dashboard -authorization_policies: - - requires_login ---- -``` - -For projects using pos-module-user, prefer the module's authorization helpers. Use native authorization policies only for simple use cases not covered by the module. - --- ## 12. Core Module @@ -898,14 +745,6 @@ You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `po ## 14. Translations (i18n) You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. -The YAML file requires top-level language key: - -``` -en: - app: - contact_form: - title: "..." -``` --- @@ -934,60 +773,7 @@ Form fields MUST use bracket notation for resource binding: Access in page: `context.params.resource` -HTML forms submit checkbox values as "on" (string), but GraphQL expects boolean field to be Boolean type, not string. - -### Form Configurations (app/forms/) - -platformOS also supports form configurations in `app/forms/` that define validation, callbacks, and processing. These are YAML + Liquid files: - -```liquid ---- -name: contact_form -resource: contact_message -resource_owner: anyone -redirect_to: /contact/thank-you -flash_notice: Message sent successfully! -fields: - properties: - name: - validation: - presence: true - email: - validation: - presence: true - email: true ---- - -{% form %} - - - -{% endform %} -``` - -The `{% form %}` tag automatically generates the `
` element with correct attributes and CSRF token. It also provides the `form` object with field metadata. - -When using the Core Module command pattern (recommended), use HTML forms with bracket notation. The `{% form %}` tag is available for simpler use cases. - -### Form Validation Error Display - -```liquid -{% if form.fields.properties.name.errors %} - {{ form.fields.properties.name.errors }} -{% endif %} -``` - -### Validation Types - -| Validation | Description | -|------------|-------------| -| `presence: true` | Field is required | -| `email: true` | Must be valid email format | -| `uniqueness: true` | Must be unique across records | -| `length: { minimum: 5, maximum: 100 }` | String length constraints | -| `numericality: { greater_than: 0 }` | Numeric range constraints | -| `confirmation: true` | Must match `_confirmation` field | -| `url: true` | Must be valid URL | +HTML forms submit checkbox values as \"on\" (string), but GraphQL expects boolean field to be Boolean type, not string. --- @@ -1108,99 +894,7 @@ Handle events via consumers: `payments_transaction_succeeded`, `payments_transac --- -## 20. Background Jobs - -Background jobs run code asynchronously outside the HTTP request cycle. - -### Syntax - -```liquid -{% background - source_name: 'send_welcome_email', - delay: 5.0, - priority: 'default', - max_attempts: 3 -%} - {% graphql user = 'users/find', id: user_id %} - {% graphql _ = 'emails/send_welcome', email: user.email %} -{% endbackground %} -``` - -### Parameters - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `source_name` | String | — | Human-readable job identifier | -| `priority` | String | `default` | `high` (1min), `default` (5min), `low` (60min) | -| `delay` | Float | 0 | Minutes to delay execution | -| `max_attempts` | Integer | 1 | Retry count (1-5) | - -### CRITICAL: Variable Scope - -Only variables **explicitly passed** to the background tag are available inside it. The `context` object is available by default but with limitations. - -**WRONG:** -```liquid -{% assign user_id = context.current_user.id %} -{% background source_name: 'job' %} - {{ user_id }} {# nil — not passed #} -{% endbackground %} -``` - -**CORRECT:** -```liquid -{% assign user_id = context.current_user.id %} -{% background source_name: 'job', user_id: user_id %} - {{ user_id }} {# Works! Explicitly passed #} -{% endbackground %} -``` - -### Priority Levels & Execution Limits - -| Priority | Max Execution | Use Case | -|----------|---------------|----------| -| `high` | 1 minute | Critical, time-sensitive tasks | -| `default` | 5 minutes | Standard operations | -| `low` | 60 minutes | Heavy processing, batch jobs | - -### Monitoring Jobs - -```graphql -query { - background_jobs( - per_page: 20 - sort: [{ created_at: { order: DESC } }] - ) { - results { - id - source_name - priority - attempts - max_attempts - created_at - started_at - completed_at - failed_at - error_message - } - } -} -``` - -### Payload Limits - -Keep background job payloads under 100KB. For large data, pass references (IDs) and fetch data inside the job: - -```liquid -{% background record_id: record_id, source_name: 'process' %} - {% graphql record = 'records/find', id: record_id %} - {# Process the record #} -{% endbackground %} -``` - ---- - -## 21. Migrations +## 20. Migrations Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications. @@ -1256,269 +950,11 @@ pos-cli migrations generate dev init_staging_constants - **done** — successfully completed (will not run again) - **error** — failed (can edit and retry) -### Migration Best Practices - -1. **Make migrations idempotent** — running twice should not cause errors: -```liquid -{% graphql record = 'records/find', id: record_id %} -{% unless record.properties.status %} - {% graphql _ = 'records/update', id: record_id, status: 'active' %} -{% endunless %} -``` - -2. **Use background jobs for large migrations:** -```liquid -{% background source_name: 'data_migration', priority: 'low' %} - {% graphql records = 'records/list_all' %} - {% for record in records.records.results %} - {# Process each record #} - {% endfor %} -{% endbackground %} -``` - -3. **Test migrations on staging first** -4. **Log progress:** -```liquid -{% log 'Migration started' %} -{% log 'Processed 50 records' %} -``` - For large data imports, use Data Import/Export instead of migrations. --- -## 22. Data Import/Export - -### Exporting Data - -```bash -# Export all data -pos-cli data export staging --path=./export.json - -# Export specific tables -pos-cli data export staging --tables=products,orders --path=./products.json -``` - -### Importing Data - -```bash -# Import data -pos-cli data import staging ./export.json - -# Import with transformations -pos-cli data import staging ./data.json --transform=./transform.js -``` - -### Export Format - -```json -{ - "users": [ - { - "id": "123", - "email": "user@example.com", - "properties": { "first_name": "John" } - } - ], - "records": { - "product": [ - { - "id": "456", - "properties": { "name": "Widget", "price": 19.99 } - } - ] - } -} -``` - -### Cleaning Instance Data - -```bash -# WARNING: Deletes all data! -pos-cli data clean staging - -# Clean specific tables -pos-cli data clean staging --tables=products,orders -``` - ---- - -## 23. JSON Documents - -JSON Documents provide schemaless data storage for flexible, document-based data. - -**Use Cases:** Configuration data, unstructured content, temporary data storage. - -### Creating JSON Documents - -```graphql -mutation { - json_document_create( - document: { - name: "site_config" - content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}" - } - ) { - id - name - content - } -} -``` - -### Querying - -```graphql -query { - json_document(name: "site_config") { - id - name - content - } - - json_documents(per_page: 10) { - results { id name content } - } -} -``` - -### Updating - -```graphql -mutation { - json_document_update( - name: "site_config" - document: { content: "{\"theme\": \"light\"}" } - ) { - id - content - } -} -``` - -### Using in Liquid - -```liquid -{% graphql config = 'json_documents/find', name: 'site_config' %} -{% assign settings = config.json_document.content | parse_json %} -Theme: {{ settings.theme }} -``` - ---- - -## 24. Activity Feeds - -Activity Feeds implement the W3C Activity Streams 2.0 specification for tracking user activities. - -**Characteristics:** Activities are immutable (append-only), each has a unique UUID. - -### Creating Activities - -```graphql -mutation { - activity_create( - activity: { - type: "Join" - actor: { type: "Person", id: "User.123", name: "John" } - object: { type: "Group", id: "Group.456" } - } - ) { - id - uuid - } -} -``` - -### Publishing to Feeds - -```graphql -mutation { - feed_publish( - feed_id: "user_123_notifications" - activity_uuid: "abc-123-uuid" - ) { id } -} -``` - -### Querying Feeds - -```graphql -query { - feeds(feed_id: "user_123_notifications", per_page: 20) { - total_entries - results { id uuid type actor object target created_at } - } -} -``` - -### Common Activity Types - -| Type | Description | -|------|-------------| -| `Create` | Created something | -| `Update` | Updated something | -| `Delete` | Deleted something | -| `Join` | Joined a group | -| `Follow` | Started following | -| `Like` | Liked content | -| `Comment` | Commented | -| `Approve` | Approved a request | - ---- - -## 25. AI Embeddings - -platformOS supports AI embeddings for semantic search and similarity matching. - -### Creating Embeddings - -```graphql -mutation { - embedding_create( - embedding: { - name: "product_description" - value: "High-quality wireless headphones" - target_id: "product_123" - target_type: "Product" - } - ) { - id - vector - } -} -``` - -### Semantic Search - -```graphql -query { - embeddings_search( - query: "wireless audio devices" - limit: 10 - threshold: 0.7 - ) { - results { - id - target_id - similarity - value - } - } -} -``` - -### Parameters - -| Parameter | Description | -|-----------|-------------| -| `name` | Embedding type identifier | -| `value` | Text to embed | -| `target_id` | Associated entity ID | -| `target_type` | Associated entity type | - ---- - -## 26. Testing +## 21. Testing Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. @@ -1535,7 +971,7 @@ Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. --- -## 27. CLI Commands +## 22. CLI Commands ```bash # Deployment @@ -1572,16 +1008,11 @@ pos-cli generate run modules/core/generators/crud --include-v # Migrations pos-cli migrations generate dev pos-cli migrations run TIMESTAMP dev - -# Data Import/Export -pos-cli data export staging --path=./export.json -pos-cli data import staging ./data.json -pos-cli data clean staging ``` --- -## 28. Modules Reference +## 23. Modules Reference | Module | Install | Purpose | Required | |--------|---------|---------|----------| @@ -1595,27 +1026,37 @@ pos-cli data clean staging --- -## 29. Forbidden Behaviors +## 24. Forbidden Behaviors You MUST NOT: - Edit files in `./modules/` (read-only) - Break long lines in `{% liquid %}` blocks (causes syntax errors) - Invent Liquid tags, filters, or GraphQL types that do not exist +- Use `{% form %}` tag (use HTML `` only) - Bypass security (CSRF tokens, authorization) - Access databases directly outside GraphQL - Deploy without running `platformos-check` - Sync files outside `./app/` +- Use `authorization_policies/` directly (use pos-module-user) +- Use `context.current_user` directly (use user module queries) +- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling) - Hardcode API keys, secrets, or environment-specific URLs - Hardcode user-facing text in partials (use translations) - Put HTML, JS, or CSS in page files - Call GraphQL from partials - Put raw GraphQL in pages (use `.graphql` files) - Create or modify application files outside the `app/` directory -- Use reserved names (`id`, `created_at`, `deleted_at`, `type_name`, `properties`) as custom property/table names +- Use more than one HTTP methods per page: +``` +#Never try to handle POST + rendering + redirect in the same root page. Keep it clean: +/ → GET → renders page +/contact (or similar) → POST → processes + redirects +``` +- Set main page methos as POST - it is not PHP! --- -## 30. Pre-Flight Checklist +## 25. Pre-Flight Checklist Before every change, verify: diff --git a/src/data/resources/short-platformos-development-guide.md b/src/data/resources/short-platformos-development-guide.md deleted file mode 100644 index ec2b2df..0000000 --- a/src/data/resources/short-platformos-development-guide.md +++ /dev/null @@ -1,1006 +0,0 @@ -# platformOS Development Guide - -Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory -workflow — read it before touching any file. - -## 0. MANDATORY WORKFLOW — Read Before Writing Any Code - -You MUST follow this loop for every feature. Each step produces structured output -the next step consumes — skipping any step produces invalid state that downstream -tools will reject. - -1. **`project_map`** — understand what already exists. MUST be called once per session - before any scaffold or write. -2. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files. - Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains - rules that are NOT in your training data and that differ from Shopify, Rails, and - generic Liquid. -3. **`scaffold(type, name, properties, write: true)`** — generate AND write the - authoritative file set from platformOS-native templates. MUST use scaffold whenever - a file set matches one of its types (crud, api, command, query, partial, page). - Scaffold output is pre-validated — no `validate_intent` or `validate_code` needed - on untouched scaffold files. `validate_intent({ scaffold_output })` is OPTIONAL - (review only, for a dry-run preview before committing). -4. **Hand-drafted files** — for files not covered by scaffold, call - `validate_intent({ intent })` (REQUIRED) then `validate_code` per file before - writing. `validate_intent` writes `pending_files`, `pending_translations`, - `pending_pages` into session state that `validate_code` and `analyze_project` - automatically merge — you do NOT need to pass them on every call. -5. **Feedback loop.** When `validate_code` returns `status !== "ok"` or - `must_fix_before_write: true`, fix every error and re-validate. MUST NOT write - a hand-drafted file to disk until validation passes. - -### MUST-CALL domains (by feature type) - -- **Auth code** — `domain_guide(domain: "authentication")` -- **Any form** — `domain_guide(domain: "forms")` -- **New pages** — `domain_guide(domain: "pages")` -- **New partials** — `domain_guide(domain: "partials")` -- **GraphQL ops** — `domain_guide(domain: "graphql")` -- **Any new domain** — `domain_guide(domain: "", section: "gotchas")` - -### MUST NOT - -- Use `{% include %}` for app code — deprecated. Use `{% render %}` or - `{% function %}`. -- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These - do not exist in platformOS. -- Write hand-drafted files to disk without calling `validate_code` on the proposed - content first. (Scaffold-written files are exempt — they are pre-validated.) -- Assume module call syntax from memory — call `module_info(name)` to get the - authoritative live-scan API surface. -- Ignore `consult_before_writing` in a scaffold response. Every domain listed there - MUST be consulted via `domain_guide` before writing. - -### Session-start checklist - -Before your first tool call, the following are true: - -- [ ] `server_status` called — confirms LSP and indexes are ready, lists - `domain_guides` and `session_pending`. -- [ ] `load_development_guide` called (this document) — re-read if you lose - context or are unsure which step comes next. -- [ ] `project_map` called once for full project baseline. - -Proceed only when all three are checked. - -## 1. Technology Stack - -platformOS uses three primary technologies: -- **Liquid** — server-side templating language -- **GraphQL** — data operations (built-in queries/mutations only) -- **YAML** — configuration for schemas, translations, and settings - -The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access. - -platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag. - -### Source of Truth - -The official platformOS documentation is the ONLY source of truth: - -| Resource | URL | -|----------|-----| -| Official Docs | documentation.platformos.com | -| GraphQL Schema | documentation.platformos.com/api/graphql/schema | -| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md | -| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md | -| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md | -| Core Module | github.com/Platform-OS/pos-module-core (README) | -| User Module | github.com/Platform-OS/pos-module-user (README) | -| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) | -| Payments Module | github.com/Platform-OS/pos-module-payments (README) | -| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) | -| Tests Module | github.com/Platform-OS/pos-module-tests (README) | -| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md | - -You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation. - ---- - -## 2. Directory Structure - -``` -project-root/ -├── app/ -│ ├── assets/ # Static files (images, fonts, styles, scripts) -│ ├── views/ -│ │ ├── pages/ # Controllers — NO HTML here -│ │ ├── layouts/ # Wrapper templates -│ │ └── partials/ # Reusable template snippets -│ ├── lib/ -│ │ ├── commands/ # Business logic (build → check → execute) -│ │ ├── queries/ # Data retrieval wrappers -│ │ ├── events/ # Event definitions -│ │ └── consumers/ # Event handlers -│ ├── schema/ # Database table definitions (YAML) -│ ├── graphql/ # GraphQL query/mutation files -│ ├── emails/ # Email templates -│ ├── smses/ # SMS templates -│ ├── api_calls/ # Third-party API integrations -│ ├── translations/ # i18n content (YAML) -│ ├── authorization_policies/ # DO NOT USE — use pos-module-user -│ ├── migrations/ # One-time migration scripts -│ └── config.yml # Feature flags -├── modules/ # Downloaded/custom modules (READ-ONLY) -└── .pos # Environment endpoints -``` - -All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`. - -The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only. - -### File Naming Conventions - -| Directory | Pattern | Example | -|-----------|---------|---------| -| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` | -| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` | -| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` | -| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` | -| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` | -| Assets | `app/assets//` | `app/assets/images/logo.png` | -| Translations | `app/translations/.yml` | `app/translations/en.yml` | - -### File Formats - -| Extension | Content-Type | URL | -|-----------|--------------|-----| -| `*.liquid` or `*.html.liquid` | `text/html` | `/path` | -| `*.json.liquid` | `application/json` | `/path.json` | -| `*.js.liquid` | `application/javascript` | `/path.js` | - ---- - -## 3. Architecture Rules - -### Pages MUST Be Controllers - -Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method. - -### Business Logic MUST Live in Commands - -All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build → check → execute pattern. - -### Path Resolution - -- `{% render 'blog_posts/card' %}` → `app/views/partials/blog_posts/card.liquid` -- `{% function r = 'commands/blog_posts/create' %}` → `app/lib/commands/blog_posts/create.liquid` -- `{% function r = 'queries/blog_posts/search' %}` → `app/lib/queries/blog_posts/search.liquid` - -The `lib/` prefix is implicit in `function` calls — do NOT include it. - -### Separation of Concerns - -- UI (Liquid templates) MUST be in partials and layouts -- Data operations (GraphQL) MUST be in query/mutation files -- Logic (commands) MUST be in `app/lib/commands/` - -### Modules First - -Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic. - -### Generators First (DEPRECATED — DO NOT USE) - -You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available. - ---- - -## 4. Pages - -Pages are controllers — they handle routing, fetch data, and delegate to partials. - -### Front Matter - -```liquid ---- -slug: products/:id -method: post -layout: application -metadata: - title: "Product Details" ---- -``` - -| Property | Default | Notes | -|----------|---------|-------| -| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` | -| `method` | `get` | `get`, `post`, `put`, `delete` | -| `layout` | `application` | Empty string for no layout | - -You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead. - -### Dynamic Routes - -| Pattern | URL | `context.params` | -|---------|-----|------------------| -| `products/:id` | `/products/123` | `{ "id": "123" }` | -| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` | -| `search(/:q)` | `/search/books` | `{ "q": "books" }` | - -### REST CRUD Convention - -| HTTP Method | URL Slug | Page File | GraphQL | Purpose | -|-------------|----------|-----------|---------|---------| -| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form | -| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource | -| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource | -| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form | -| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource | -| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource | -| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources | - -### CSRF Protection - -Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous). - -### GET Page Example - -```liquid ---- -slug: articles/:id -method: get ---- -{% liquid - function article = 'queries/articles/find', id: context.params.id - - if article == blank - render '404' - break - endif - - render 'articles/show', article: article -%} -``` - -### POST Page Example - -```liquid ---- -slug: articles -method: post ---- -{% liquid - function result = 'commands/articles/create', object: context.params.article - - if result.valid - function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname - redirect_to '/articles' - else - render 'articles/new', result: result - endif -%} -``` - ---- - -## 5. Partials & Layouts - -### Partials - -Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`). - -Partials MUST NOT have underscore-prefixed filenames. - -The render path maps: `render 'path/name'` → `app/views/partials/path/name.liquid`. - -### Layouts - -The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout. - ---- - -## 6. Commands (Business Logic) - -All business logic MUST be encapsulated in commands following the build → check → execute pattern. - -### Main Command - -```liquid -{% doc %} - @param object {object} - Article data -{% enddoc %} - -{% liquid - function object = 'commands/articles/create/build', object: object - function object = 'commands/articles/create/check', object: object - - if object.valid - function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object - endif - - return object -%} -``` - -### Build Stage - -Normalizes and structures input data: - -```liquid -{% doc %} - @param object {object} - form params -{% enddoc %} - -{% liquid - assign object['title'] = object.title - assign object['body'] = object.body - - return object -%} -``` - -### Check Stage - -Validates the built object: - -```liquid -{% doc %} - @param object {object} - form params -{% enddoc %} - -{% liquid - assign c = '{ "errors": {}, "valid": true }' | parse_json - - function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title' - function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body' - - assign object = object | hash_merge: valid: c.valid, errors: c.errors - - return object -%} -``` - -### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE) - -> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`). - -```liquid -{% comment %} WRONG — these partials do not exist: {% endcomment %} -{% function object = 'modules/core/commands/build', object: object %} -{% function object = 'modules/core/commands/check', object: object, - validators: '[{"name": "presence", "property": "title"}]' -%} - -{% comment %} CORRECT — only execute is shared: {% endcomment %} -{% if object.valid %} - {% function object = 'modules/core/commands/execute', - mutation_name: 'products/create', selection: 'record', object: object - %} -{% endif %} - -{% return object %} -``` - -### Events - -```liquid -{% comment %} Publish an event {% endcomment %} -{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %} - -{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %} -{% graphql _ = 'emails/send_confirmation', email: event.object.email %} -``` - -All inputs MUST be validated in commands before persisting. - ---- - -## 7. GraphQL - -GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively. - -### Query Wrapper Pattern - -```liquid -{% doc %} - @param id {string} - Article ID -{% enddoc %} - -{% liquid - graphql result = 'articles/find', id: id - return result.records.results | first -%} -``` - -### Search with Pagination - -```graphql -query search($page: Int = 1, $keyword: String) { - records( - page: $page - per_page: 20 - filter: { - table: { value: "article" } - properties: [{ name: "title", contains: $keyword }] - } - sort: { created_at: { order: DESC } } - ) { - total_pages - results { - id - title: property(name: "title") - body: property(name: "body") - } - } -} -``` - -All list queries MUST support `per_page` and `page` arguments for pagination. - -### Find by ID - -```graphql -query find($id: ID!) { - records( - per_page: 1 - filter: { - id: { value: $id } - table: { value: "article" } - } - ) { - results { - id - title: property(name: "title") - } - } -} -``` - -### Related Records (Avoids N+1) - -```graphql -results { - id - # belongs-to (single) - author: related_record(table: "user", join_on_property: "user_id") { - email - } - # has-many - comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") { - body: property(name: "body") - } -} -``` - -### Upload Property - -```graphql -image: property_upload(name: "image") { url } -``` - -### Mutations - -All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`: - -- `record: record_create(record: { table: "...", properties: [...] }) { id }` -- `record: record_update(id: $id, record: { properties: [...] }) { id }` -- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table" - -### Pagination Component - -```liquid -{% graphql result = 'products/search', page: context.params.page %} -{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %} -``` - ---- - -## 8. Schema - -Schema files define database tables in YAML at `app/schema/`. - -```yaml -# app/schema/article.yml -name: article -properties: - - name: title - type: string - - name: body - type: text - - name: published_at - type: datetime - - name: image - type: upload - options: - acl: public -``` - -### Property Types - -`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload` - ---- - -## 9. Liquid Reference - -### Tags - -```liquid -{% graphql result = 'query_name', arg: value %} -{% function result = 'path/to/partial', arg: value %} -{% render 'partial', var: value %} -{% doc %} @param name {Type} - description {% enddoc %} -{% return result %} -{% export my_var, namespace: 'my_ns' %} -{% parse_json data %}{"key": "value"}{% endparse_json %} -{% redirect_to '/path', status: 302 %} -{% session key = value %} -{% log variable, type: 'debug' %} -{% cache 'key', expire: 3600 %}...{% endcache %} -{% background source_name: 'job_name', priority: 'low' %}...{% endbackground %} -{% content_for_layout %} -{% theme_render_rc 'modules/common-styling/toasts' %} -``` - -**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is). - -### Output - -```liquid -{{ variable }} -{{ variable | html_safe }} -{% print variable %} -``` - -### Common Filters - -- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by` -- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys` -- **Dates:** `add_to_time`, `localize`, `is_date_in_past` -- **Validation:** `is_email_valid`, `is_json_valid` -- **Encoding:** `json`, `base64_encode`, `url_encode` - -### Coding Standards - -You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line. - -**Correct:** -```liquid -{% liquid - assign filtered = products | where: 'available', true | map: 'title' | first - assign price = product | where: 'id', pid | map: 'price' | first -%} -``` - -**WRONG (causes syntax errors):** -```liquid -{% liquid - assign filtered = products - | where: 'available', true - | map: 'title' - | first -%} -``` - ---- - -## 10. Global Context - -**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results. - -| Property | Description | -|----------|-------------| -| `context.params` | HTTP parameters (query string + body) | -| `context.session` | Server-side session storage | -| `context.location` | URL info (`pathname`, `search`, `host`) | -| `context.environment` | `staging` or `production` | -| `context.is_xhr` | `true` for AJAX requests | -| `context.authenticity_token` | CSRF token | -| `context.constants` | Environment constants (hidden from `{{ context }}` for security) | -| `context.page.metadata` | Page metadata from front matter | - -You MUST NOT use `context.current_user` directly — always use `modules/user/queries/user/current`. - ---- - -## 11. User Module (Authentication & Authorization) - -You MUST use the User Module for all authentication and authorization. You MUST NOT use `authorization_policies/` directly. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested. - -### Built-in Roles - -- **Anonymous** — unauthenticated users -- **Authenticated** — any logged-in user -- **Superadmin** — bypasses ALL permission checks - -### Authorization Helpers - -```liquid -{% function profile = 'modules/user/queries/user/current' %} - -{% comment %} Check permission (returns true/false) {% endcomment %} -{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %} - -{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %} -{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %} - -{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %} -{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %} -``` - -> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`. - -### Custom Permissions - -Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`: - -```bash -mkdir -p app/modules/user/public/lib/queries/role_permissions -cp modules/user/public/lib/queries/role_permissions/permissions.liquid \ - app/modules/user/public/lib/queries/role_permissions/permissions.liquid -``` - -Define roles: -```liquid -{% parse_json data %} -{ - "admin": ["admin.view", "users.manage"], - "editor": ["article.create", "article.update"], - "superadmin": [] -} -{% endparse_json %} -{% return data %} -``` - ---- - -## 12. Core Module - -You MUST use pos-module-core for commands, events, and validators. - ---- - -## 13. Common Styling - -You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components. - -### Setup - -```liquid -{% comment %} In {% endcomment %} -{% render 'modules/common-styling/init' %} -``` -```html - -``` - -### File Upload Component - -```liquid -{% render 'modules/common-styling/forms/upload', - id: 'image', presigned_upload: presigned, name: 'image', - allowed_file_types: ['image/*'], max_number_of_files: 5 -%} -``` - ---- - -## 14. Translations (i18n) - -You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`. - ---- - -## 15. Forms - -You MUST use HTML `` tags. You MUST NOT use `{% form %}`. - -Forms MUST include the CSRF token: -```html - -``` - -For PUT/DELETE, forms MUST use POST with a `_method` hidden field: -```html - - - - - -``` - -Form fields MUST use bracket notation for resource binding: -```html - -``` - -Access in page: `context.params.resource` - -HTML forms submit checkbox values as \"on\" (string), but GraphQL expects boolean field to be Boolean type, not string. - ---- - -## 16. Constants & Credentials - -You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`. - -### Setting Constants - -**Via CLI:** -```bash -pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev -pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev -pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev -``` - -**Via GraphQL:** -```graphql -mutation { - constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") { - name - } -} -``` - -### Accessing Constants in Liquid - -Constants are hidden from `{{ context }}` for security. You MUST access them explicitly: -```liquid -{{ context.constants.STRIPE_SK_KEY }} -{{ context.constants.API_BASE_URL }} -``` - -### Naming Conventions - -| Use Case | Example | -|----------|---------| -| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` | -| API URLs | `API_BASE_URL` | -| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` | - -Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically. - ---- - -## 17. Flash Messages & Toasts - -### Layout Setup (before ``) - -```liquid -{% liquid - function flash = 'modules/core/commands/session/get', key: 'sflash' - if context.location.pathname != flash.from or flash.force_clear - function _ = 'modules/core/commands/session/clear', key: 'sflash' - endif - render 'modules/common-styling/toasts', params: flash -%} -``` - -### Liquid Usage - -```liquid -{% liquid - function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname - redirect_to '/orders' -%} -``` - -### JavaScript Usage - -```javascript -new pos.modules.toast('success', 'Saved!'); -new pos.modules.toast('error', 'Failed'); -``` - ---- - -## 18. Notifications (Email/SMS) - -```liquid -{% comment %} app/emails/order_confirmation.liquid {% endcomment %} ---- -to: {{ data.email }} -from: shop@example.com -subject: "Order #{{ data.order_id }}" -layout: mailer ---- -

Thank you for your order!

-``` - -Emails SHOULD be sent asynchronously using events + consumers. - ---- - -## 19. Payments (Stripe) - -### Install - -```bash -pos-cli modules install payments && pos-cli modules install payments_stripe -pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev -``` - -### Create Transaction - -```liquid -{% function transaction = 'modules/payments/commands/transactions/create', - gateway: 'stripe', email: email, line_items: items, - success_url: '/thank-you', cancel_url: '/cart' -%} -{% function url = 'modules/payments/queries/pay_url', transaction: transaction %} -{% redirect_to url, status: 303 %} -``` - -Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed` - -**Test card:** `4242 4242 4242 4242`, any future date, any CVC. - ---- - -## 20. Migrations - -Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications. - -### File Structure - -``` -app/migrations/ -├── 20240115120000_seed_initial_data.liquid -├── 20240116093000_add_default_categories.liquid -└── 20240120150000_init_staging_constants.liquid -``` - -Files MUST be named with UTC timestamp prefix for chronological execution. - -### Creating a Migration - -```bash -pos-cli migrations generate dev init_staging_constants -# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid -``` - -### Example: Initialize Staging Constants - -```liquid -{% liquid - if context.environment == 'staging' - graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123' - graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com' - endif -%} -``` - -### Example: Seed Data - -```liquid -{% parse_json categories %} -["Electronics", "Clothing", "Books"] -{% endparse_json %} - -{% for category in categories %} - {% graphql _ = 'categories/create', name: category %} -{% endfor %} -``` - -### Running Migrations - -- **Automatic:** Pending migrations run on `pos-cli deploy` -- **Manual:** `pos-cli migrations run TIMESTAMP dev` - -### Migration States - -- **pending** — not yet executed (runs on next deploy) -- **done** — successfully completed (will not run again) -- **error** — failed (can edit and retry) - -For large data imports, use Data Import/Export instead of migrations. - ---- - -## 21. Testing - -Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development. - -Every new feature MUST have unit tests for commands. - -```liquid -{% function result = 'commands/products/create', title: "Test" %} -{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %} -{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %} -{% return contract %} -``` - -Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI. - ---- - -## 22. CLI Commands - -```bash -# Deployment -pos-cli deploy dev - -# Sync (MUST sync every file after modification) -pos-cli sync dev - -# Logs -pos-cli logs dev - -# Linting (MUST run after EVERY file change) -platformos-check - -# Run Liquid inline -pos-cli exec liquid dev '' - -# Run GraphQL inline -pos-cli exec graphql dev '' - -# Tests -pos-cli test run staging - -# Modules -pos-cli modules install -pos-cli modules download - -# Constants -pos-cli constants set --name KEY --value "value" dev - -# Generate CRUD -pos-cli generate run modules/core/generators/crud --include-views - -# Migrations -pos-cli migrations generate dev -pos-cli migrations run TIMESTAMP dev -``` - ---- - -## 23. Modules Reference - -| Module | Install | Purpose | Required | -|--------|---------|---------|----------| -| `core` | Required | Commands, events, validators | YES | -| `user` | Required | Auth, RBAC, OAuth2 | YES | -| `common-styling` | Required | CSS, components | YES | -| `tests` | Optional | Testing framework | YES (for testing) | -| `payments` + `payments_stripe` | Optional | Stripe payments | No | -| `chat` | Optional | WebSocket messaging | No | -| `openai` | Optional | OpenAI integration | No | - ---- - -## 24. Forbidden Behaviors - -You MUST NOT: -- Edit files in `./modules/` (read-only) -- Break long lines in `{% liquid %}` blocks (causes syntax errors) -- Invent Liquid tags, filters, or GraphQL types that do not exist -- Use `{% form %}` tag (use HTML `
` only) -- Bypass security (CSRF tokens, authorization) -- Access databases directly outside GraphQL -- Deploy without running `platformos-check` -- Sync files outside `./app/` -- Use `authorization_policies/` directly (use pos-module-user) -- Use `context.current_user` directly (use user module queries) -- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling) -- Hardcode API keys, secrets, or environment-specific URLs -- Hardcode user-facing text in partials (use translations) -- Put HTML, JS, or CSS in page files -- Call GraphQL from partials -- Put raw GraphQL in pages (use `.graphql` files) -- Create or modify application files outside the `app/` directory - ---- - -## 25. Pre-Flight Checklist - -Before every change, verify: - -- [ ] No underscore prefix in partial filenames -- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid` -- [ ] Pages have ONE HTTP method each -- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files) -- [ ] No HTML/JS/CSS in pages -- [ ] No hardcoded text in partials (use translations) -- [ ] `platformos-check` passes with 0 errors -- [ ] Every file synced after modification -- [ ] All list queries support pagination (`per_page`, `page`) -- [ ] All inputs validated in commands before persisting -- [ ] CSS/JS minified, `asset_url` used for cache busting - -### Asset URL Usage - -```liquid -{{ 'images/img.png' | asset_url }} -``` diff --git a/src/http-server.js b/src/http-server.js index 6537e3d..133aae8 100644 --- a/src/http-server.js +++ b/src/http-server.js @@ -10,11 +10,12 @@ import { HTTP_MAX_BODY } from './core/constants.js'; import { buildDashboardHtml } from './dashboard.js'; import { getProjectMap } from './tools/project-map.js'; import { buildDependencyGraph } from './core/dependency-graph.js'; -import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory, ruleDrilldown } from './core/analytics-queries.js'; +import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory, ruleDrilldown, rulePerformance, adaptiveModeImpact, fixRulePerformance } from './core/analytics-queries.js'; import { ruleScores, suggestedRules, retrieveCasesByCheck, generateRuleTemplate, synthesizeGuardPredicate } from './core/case-base.js'; import { addPromotedRule, removePromotedRule, listPromotedRules } from './core/rules/promoted-rules.js'; import { reloadRules, loadAllRules } from './core/rules/index.js'; -import { runRules, getDisabledRules, getAllChecksWithRules, getRulesForCheck } from './core/rules/engine.js'; +import { runRules, getDisabledRules, getAllChecksWithRules, getRulesForCheck, getDisabledRuleDetails, getForceEnabledRules, getForceDisabledRules } from './core/rules/engine.js'; +import { loadOverrides, addForceEnable, addForceDisable, removeOverride } from './core/rule-overrides.js'; import { extractParams, templateOf, KNOWN_EXTRACTOR_CHECKS } from './core/diagnostic-record.js'; import { buildFactGraph } from './core/project-fact-graph.js'; @@ -22,7 +23,7 @@ import { buildFactGraph } from './core/project-fact-graph.js'; * HTTP server — REST endpoints for tool discovery, execution, and resources. * MCP protocol (JSON-RPC over stdio) is handled by the SDK transport in server.js. */ -export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild, switchEngineMode, getEngineMode }) { +export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild, onOverridesChanged, switchEngineMode, getEngineMode }) { if (!port) return null; const dashboardHtml = buildDashboardHtml(); @@ -168,6 +169,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re if (url.pathname === '/api/rules/test') { return handleRuleTest(body, res, analyticsStore, projectDir); } + + if (url.pathname === '/api/engine/rule-overrides') { + return handleRuleOverridesMutate(projectDir, body, res, log, onOverridesChanged); + } } // ── Analytics GET routes ────────────────────────────────────────────── @@ -196,6 +201,14 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re return handleRuleScores(analyticsStore, url, res); } + if (method === 'GET' && url.pathname === '/api/analytics/rule-performance') { + return handleRulePerformance(analyticsStore, url, res); + } + + if (method === 'GET' && url.pathname === '/api/analytics/fix-rule-performance') { + return handleFixRulePerformance(analyticsStore, url, res); + } + if (method === 'GET' && url.pathname === '/api/analytics/rule-drilldown') { return handleRuleDrilldown(analyticsStore, url, res); } @@ -240,6 +253,20 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re return handleEngineMap(analyticsStore, res); } + if (method === 'GET' && url.pathname === '/api/blob') { + return handleBlobRead(blobStore, url, res); + } + + if (method === 'GET' && url.pathname === '/api/engine/impact') { + return handleEngineImpact(analyticsStore, url, res); + } + + if (method === 'GET' && url.pathname === '/api/engine/rule-overrides') { + return handleRuleOverridesList(projectDir, res, log); + } + // POST on this path is dispatched inside the POST block above so the + // shared body-parser isn't read twice. + // ── Fallback ──────────────────────────────────────────────────────── sendJson(res, 404, { error: 'Not found' }); }); @@ -989,6 +1016,111 @@ function handleEngineMap(analyticsStore, res) { } } +function handleBlobRead(blobStore, url, res) { + if (!blobStore) return sendJson(res, 503, { error: 'blob store not available' }); + const hash = url.searchParams.get('hash'); + if (!hash || !/^[0-9a-f]{64}$/i.test(hash)) { + return sendJson(res, 400, { error: 'hash must be a 64-char hex SHA256 string' }); + } + const text = blobStore.getText(hash); + if (text == null) return sendJson(res, 404, { error: 'blob not found' }); + return sendJson(res, 200, { text }); +} + +/** + * GET /api/engine/impact + * + * Returns the adaptive-mode impact summary: what rules are currently + * disabled/promoted/overridden, window-scoped emit counts and the split + * between rules that *would* fire under static mode (currently disabled) + * vs adaptive (currently firing). Payload is a merge of the live engine + * state (not in the DB) and adaptiveModeImpact() (DB-derived window query). + */ +function handleEngineImpact(analyticsStore, url, res) { + if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); + try { + const windowMs = parseInt(url.searchParams.get('window_ms') || String(86_400_000), 10); + const impact = adaptiveModeImpact(analyticsStore, { windowMs }); + + const disabled = getDisabledRuleDetails(); + const forceEnabled = [...getForceEnabledRules()]; + const forceDisabled = [...getForceDisabledRules()]; + + // Counterfactual: sum window emits that hit currently-disabled rule_ids. + // These are the diagnostics the operator would have seen under static + // mode. A rule in force_enabled is disabled-by-data but running anyway, + // so it still contributes to the adaptive view — exclude it from the + // suppressed sum. + let suppressed_by_disabled = 0; + const per_rule_suppressed = {}; + for (const row of disabled) { + if (row.force_enabled) continue; + const hits = impact.emits_by_rule[row.rule_id] ?? 0; + if (hits > 0) { + suppressed_by_disabled += hits; + per_rule_suppressed[row.rule_id] = hits; + } + } + + return sendJson(res, 200, { + window: { + ms: impact.window_ms, + start: impact.window_start, + end: impact.window_end, + }, + emits_in_window: impact.emits_in_window, + rule_matched_in_window: impact.rule_matched_in_window, + confidence: impact.confidence, + disabled_rules: disabled, + force_enabled: forceEnabled, + force_disabled: forceDisabled, + counterfactual: { + suppressed_by_disabled, + per_rule_suppressed, + }, + }); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + +function handleRuleOverridesList(projectDir, res, log) { + try { + const state = loadOverrides(projectDir, { log }); + sendJson(res, 200, state); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + +/** + * POST /api/engine/rule-overrides + * + * Body: `{ action: 'force_enable' | 'force_disable' | 'clear', rule_id: string, reason?: string }`. + * + * clear → removes any override for the rule. The `onOverridesChanged` hook + * re-reads the file into the engine and runs `syncDisabledRules` so the + * effect is visible immediately without restart. + */ +function handleRuleOverridesMutate(projectDir, body, res, log, onOverridesChanged) { + const { action, rule_id, reason } = body ?? {}; + if (!rule_id || typeof rule_id !== 'string') { + return sendJson(res, 400, { error: 'rule_id required' }); + } + try { + let state; + if (action === 'force_enable') state = addForceEnable(projectDir, rule_id, reason ?? '', { log }); + else if (action === 'force_disable') state = addForceDisable(projectDir, rule_id, reason ?? '', { log }); + else if (action === 'clear') state = removeOverride(projectDir, rule_id, { log }); + else return sendJson(res, 400, { error: 'action must be force_enable | force_disable | clear' }); + + try { onOverridesChanged?.(); } catch (e) { log(`onOverridesChanged failed: ${e.message}`); } + sendJson(res, 200, state); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + // ── Helpers ─────────────────────────────────────────────────────────────── function sendJson(res, status, data) { @@ -1083,6 +1215,28 @@ function handleRuleScores(analyticsStore, url, res) { } } +function handleRulePerformance(analyticsStore, url, res) { + if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); + try { + const minEmitted = parseInt(url.searchParams.get('min_emitted') || '1', 10); + const scores = rulePerformance(analyticsStore, { minEmitted }); + sendJson(res, 200, { scores }); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + +function handleFixRulePerformance(analyticsStore, url, res) { + if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); + try { + const minProposed = parseInt(url.searchParams.get('min_proposed') || '1', 10); + const scores = fixRulePerformance(analyticsStore, { minProposed }); + sendJson(res, 200, { scores }); + } catch (e) { + sendJson(res, 500, { error: e.message }); + } +} + function handleRuleDrilldown(analyticsStore, url, res) { if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' }); try { diff --git a/src/server.js b/src/server.js index e4444d3..af54a19 100644 --- a/src/server.js +++ b/src/server.js @@ -14,8 +14,9 @@ import { startFsWatcher } from './core/fs-watcher.js'; import { invalidateProjectMap } from './tools/project-map.js'; import { createToolRegistry } from './tools.js'; import { initPromotedRules, reloadRules } from './core/rules/index.js'; -import { updateDisabledRules } from './core/rules/engine.js'; +import { updateDisabledRules, updateForceOverrides, setDisabledRuleDetails } from './core/rules/engine.js'; import { ruleScores, resolveProbation } from './core/case-base.js'; +import { loadOverrides, overrideSets } from './core/rule-overrides.js'; import { loadEngineMode, isAdaptive, setEngineMode, getEngineMode } from './core/engine-mode.js'; import { startHttp } from './http-server.js'; import { createLogger } from './core/logger.js'; @@ -70,7 +71,10 @@ export async function createServer({ projectDir, httpPort = 0 }) { // ── Analytics store (Phase B — derived from NDJSON, disposable) ──────────── let analyticsStore = null; try { - analyticsStore = openAnalyticsStore(join(projectDir, '.pos-supervisor', 'analytics.db')); + analyticsStore = openAnalyticsStore( + join(projectDir, '.pos-supervisor', 'analytics.db'), + { blobStore }, + ); log('analytics-store: opened'); } catch (e) { log(`analytics-store: failed to open (${e.message}); analytics will not be available`); @@ -114,10 +118,29 @@ export async function createServer({ projectDir, httpPort = 0 }) { } } - // ── Disabled rule enforcement (Phase J4) ───────────────────────────────────── + // ── Disabled rule enforcement (Phase J4 + I4 operator overrides) ───────────── + // force-enable wins over case-base disable; force-disable applies always. + // Engine picks up the split via ruleIsActive; sync loads file → engine so + // edits made through the dashboard take effect without restart. + function syncRuleOverrides() { + try { + const state = loadOverrides(projectDir, { log }); + const { force_enable, force_disable } = overrideSets(state); + updateForceOverrides({ force_enable, force_disable }); + if (force_enable.size || force_disable.size) { + log(`rule-overrides: ${force_enable.size} force-enabled, ${force_disable.size} force-disabled`); + } + return state; + } catch (e) { + log(`rule-overrides: sync failed (${e.message})`); + return { force_enable: {}, force_disable: {} }; + } + } + function syncDisabledRules() { if (!isAdaptive()) { updateDisabledRules(null); + setDisabledRuleDetails([]); return; } if (!analyticsStore) return; @@ -125,11 +148,16 @@ export async function createServer({ projectDir, httpPort = 0 }) { const scores = ruleScores(analyticsStore, { minEmitted: 5 }); const disabled = scores.filter(s => s.disabled).map(s => s.rule_id); updateDisabledRules(disabled); + setDisabledRuleDetails(scores.filter(s => s.disabled)); if (disabled.length > 0) log(`disabled-rules: ${disabled.length} rule(s) disabled by analytics`); } catch (e) { log(`disabled-rules: sync failed (${e.message})`); } } + + // Order matters: overrides first so the disabled-rules sync below sees + // them in effect. Both are idempotent — safe to call repeatedly. + syncRuleOverrides(); syncDisabledRules(); // ── Engine mode transitions ────────────────────────────────────────────────── @@ -699,7 +727,7 @@ export async function createServer({ projectDir, httpPort = 0 }) { }; } const dataRoot = join(__dirname, 'data'); - startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, onAnalyticsRebuild: syncDisabledRules, switchEngineMode, getEngineMode }); + startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild: syncDisabledRules, onOverridesChanged: () => { syncRuleOverrides(); syncDisabledRules(); }, switchEngineMode, getEngineMode }); } // ── Graceful shutdown ───────────────────────────────────────────────────── diff --git a/src/tools.js b/src/tools.js index f0eccab..40acb16 100644 --- a/src/tools.js +++ b/src/tools.js @@ -81,7 +81,19 @@ export function createToolRegistry(ctx, mcpServer = null) { } if (untracked) { - return rawHandler(cleanArgs); + // `ctx.untracked = true` is read by tool handlers that emit directly + // to sessionBus (currently validate-code.js → `validator_emit`). The + // flag is transient — restore the previous value in a finally so a + // tool handler that happens to trigger another tool mid-flight does + // not lose state. Single-threaded event loop: concurrent calls + // already share ctx, so this is consistent with existing practice. + const prevUntracked = ctx.untracked; + ctx.untracked = true; + try { + return await rawHandler(cleanArgs); + } finally { + ctx.untracked = prevUntracked; + } } const start = Date.now(); diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js index 374a31c..0b4cf11 100644 --- a/src/tools/validate-code.js +++ b/src/tools/validate-code.js @@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'; import { parseLiquidFile, extractAllFromAST } from '../core/liquid-parser.js'; import { checkContent } from '../core/check-runner.js'; import { normalizeLspDiagnostics } from '../core/lsp-client.js'; -import { enrichAll } from '../core/error-enricher.js'; +import { enrichAll, bridgeRulesOntoUnattributed } from '../core/error-enricher.js'; import { generateFixes, clusterDiagnostics, generateScorecard } from '../core/fix-generator.js'; import { getDomainFromPath, getDomainHeader } from '../core/domain-detector.js'; import { getTriggeredGotchas, getContentTriggers } from '../core/knowledge-loader.js'; @@ -11,7 +11,8 @@ import { generateStructuralWarnings } from '../core/structural-warnings.js'; import { validateSchema } from '../core/schema-validator.js'; import { validateTranslationYaml } from '../core/translation-validator.js'; import { checkSchemaProperties } from '../core/schema-property-checker.js'; -import { runDiagnosticPipeline } from '../core/diagnostic-pipeline.js'; +import { runDiagnosticPipeline, stampDefaultsOn } from '../core/diagnostic-pipeline.js'; +import { isCheckForceDisabled } from '../core/rules/engine.js'; import { partitionCallersByPending } from '../core/pending-callers.js'; import { toUri, sanitizePath } from '../core/utils.js'; import { fingerprint, templateFingerprint, messageTemplate, extractParams } from '../core/diagnostic-record.js'; @@ -682,6 +683,59 @@ explicitly only if you are validating a file that is NOT part of the most recent if (d.endLine != null) d.endLine += 1; } + // 12a. Run rule-engine rules against diagnostics that didn't pass through + // enrichAll (structural warnings, schema / translation / GraphQL + // validators, diff-aware RemovedRender/AddedParam, new-partial + // caller check). Rule modules for structural checks (like + // `pos-supervisor:NonGetRenderingPage`) register against the check + // name but only fire inside error-enricher.enrichAll, which ran + // before these diagnostics were pushed. This bridge lets their + // rules fire, attaching the rule_id + hint_md that would otherwise + // be lost — see the 2026-04-24 DEMO report finding. + try { + const projectMapForBridge = await getProjectMap(ctx.directory); + const factGraphForBridge = buildFactGraph(projectMapForBridge); + bridgeRulesOntoUnattributed(result, { + filePath: file_path, + content, + factGraph: factGraphForBridge, + filtersIndex: ctx.filtersIndex, + objectsIndex: ctx.objectsIndex, + tagsIndex: ctx.tagsIndex, + schemaIndex: ctx.schemaIndex, + analyticsStore: ctx.analyticsStore, + }); + } catch { /* bridge is best-effort — fall through to default stamping */ } + + // 12b. Re-stamp default confidence + rule_id across the final diagnostic + // set. runDiagnosticPipeline already ran this as its last step, but + // several sources push into result.errors / result.warnings AFTER + // the pipeline finishes (structural warnings, schema validation, + // translation YAML check, diff-aware RemovedRender/AddedParam, the + // new-partial caller check). Without this second pass those late + // additions land in the analytics store with confidence = null and + // no rule_id, breaking the calibration chart and rule-performance + // attribution. Idempotent — the helper only fills when a field is + // missing. See the 2026-04-23 DEMO report finding. + stampDefaultsOn(result); + + // 12b. Apply force-disable overrides at the check-name level. + // + // runRules() already honors force-disable for rule_ids, but many + // diagnostics originate outside the rule engine — structural + // warnings (pos-supervisor:*), LSP checks without a rule module. + // An operator who force-disables a check like "pos-supervisor:HtmlInPage" + // expects the diagnostic to stop appearing entirely, not just the + // (nonexistent) rule to stop firing. Filter here so the override + // semantics match operator intent. Also covers rule_id-level + // disables as a belt-and-braces second gate (a rule that fires + // despite _forceDisabled containing its id gets dropped here too). + const dropForceDisabled = (d) => + !(isCheckForceDisabled(d.check) || isCheckForceDisabled(d.rule_id)); + result.errors = result.errors.filter(dropForceDisabled); + result.warnings = result.warnings.filter(dropForceDisabled); + result.infos = result.infos.filter(dropForceDisabled); + // 12. Strip null hint fields — diagnostics without hints should omit the field // entirely rather than returning hint: null which looks like a bug in the output. for (const d of [...result.errors, ...result.warnings, ...result.infos]) { @@ -690,7 +744,9 @@ explicitly only if you are validating a file that is NOT part of the most recent // 13. Emit validator_emit events — one per diagnostic shown to the agent. // Best-effort: failures never propagate into the tool response. - if (ctx.sessionBus) { + // Skipped when ctx.untracked is set (dashboard live-console calls) so + // experimental validations don't pollute the analytics store. + if (ctx.sessionBus && !ctx.untracked) { try { const contentHash = ctx.blobStore ? ctx.blobStore.put(content) : null; for (const d of [...result.errors, ...result.warnings]) { @@ -698,10 +754,28 @@ explicitly only if you are validating a file that is NOT part of the most recent const fp = fingerprint(d.check, file_path, tmpl); const tFp = templateFingerprint(d.check, tmpl); const hintHash = d.hint && ctx.blobStore ? ctx.blobStore.put(d.hint) : null; - const fixes = (d.proposed_fixes || []).map(f => ({ + // Union both fix channels so analytics sees every proposal the agent + // saw: rule engine → d.fixes (plural), heuristic fix-generator → d.fix + // (singular). Both use the same { type, range, new_text, ... } shape. + // Each fix carries its own rule_id so Rule Performance can attribute + // adoption to a specific rule-engine or heuristic-generator branch + // (I1). The rule-engine path stamps rule_id on the rule's HintResult; + // the heuristic path stamps `heuristic:.` centrally + // inside generateFixes. + const diagFixes = [ + ...(Array.isArray(d.fixes) ? d.fixes : []), + ...(d.fix ? [d.fix] : []), + ]; + const fixes = diagFixes.map(f => ({ range: f.range ?? null, - new_text_hash: ctx.blobStore ? ctx.blobStore.put(f.newText || '') : '', - kind: f.kind || 'unknown', + new_text_hash: ctx.blobStore && f.new_text ? ctx.blobStore.put(f.new_text) : null, + kind: f.type || 'unknown', + // Rule-engine rules attach rule_id to the HintResult (and therefore + // to d.rule_id), not to each individual fix object. Heuristic + // fixes carry their own rule_id from fix-generator's central stamp. + // Falling back to d.rule_id lets rule-engine fixes inherit the + // matching rule's id so fixRulePerformance can attribute them. + rule_id: f.rule_id ?? d.rule_id ?? null, })); const diagParams = extractParams(d.check, d.message || ''); ctx.sessionBus.emit('validator_emit', { diff --git a/tests/integration/analytics/fix-rule-attribution.test.js b/tests/integration/analytics/fix-rule-attribution.test.js new file mode 100644 index 0000000..33420c1 --- /dev/null +++ b/tests/integration/analytics/fix-rule-attribution.test.js @@ -0,0 +1,94 @@ +/** + * I1 follow-up — fix proposals must carry rule_id even when the rule-engine + * attaches rule_id to the HintResult rather than to each fix. + * + * Prior to this fix, rule-engine rules like `MissingPartial.create_file` + * produced proposed_fixes rows with rule_id = NULL because the rule's + * `apply()` returns { rule_id: 'MissingPartial.create_file', fixes: [...] } + * — the id lives on the result, not the fix object. The emit loop only + * read f.rule_id and lost the attribution. + * + * The fix is a single `f.rule_id ?? d.rule_id` fallback in validate-code.js. + * This test drives a real validate_code call that triggers a rule-engine + * fix and asserts the emitted event carries the inherited rule_id. + */ + +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { readFileSync, readdirSync, existsSync } from 'node:fs'; +import { join } from 'node:path'; +import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js'; + +setDefaultTimeout(30_000); + +let server; +let proj; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +function readValidatorEmits(projectDir) { + const sessionsDir = join(projectDir, '.pos-supervisor', 'sessions'); + if (!existsSync(sessionsDir)) return []; + const entries = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()); + const out = []; + for (const entry of entries) { + const eventsPath = join(sessionsDir, entry.name, 'events.ndjson'); + if (!existsSync(eventsPath)) continue; + for (const line of readFileSync(eventsPath, 'utf-8').split('\n').filter(Boolean)) { + try { + const ev = JSON.parse(line); + if (ev.kind === 'validator_emit') out.push(ev); + } catch { /* skip */ } + } + } + return out; +} + +describe('emit-loop propagates rule_id onto every fix (I1 follow-up)', () => { + // A page rendering a partial that doesn't exist triggers MissingPartial. + // In quick mode the rule engine's `MissingPartial.create_file` branch fires + // (priority 20 — nearest-match is priority 10, won't hit for a truly + // unknown name). Its HintResult carries rule_id AND fixes[0] is a + // create_file. The fix object itself has no rule_id — we're testing that + // the emit loop inherits d.rule_id. + it('MissingPartial.create_file fix inherits rule_id from the diagnostic', async () => { + const FILE = 'app/views/pages/rule-attr-test.liquid'; + const CONTENT = '---\nslug: rule-attr-test\n---\n{% render "totally/nonexistent_partial_xyz" %}\n'; + + await server.callTool('validate_code', { + file_path: FILE, + content: CONTENT, + mode: 'full', + }); + + await new Promise(r => setTimeout(r, 100)); + + const emits = readValidatorEmits(proj.dir); + const mpEmit = emits.find( + e => e.file === FILE && e.check === 'MissingPartial' && (e.proposed_fixes?.length ?? 0) > 0, + ); + expect(mpEmit).toBeDefined(); + expect(mpEmit.hint_rule_id).toContain('MissingPartial'); + + // Every fix attached to this diagnostic carries a rule_id — either its + // own (heuristic:...) or inherited from the rule engine's d.rule_id. + for (const fix of mpEmit.proposed_fixes) { + expect(fix.rule_id).not.toBeNull(); + expect(typeof fix.rule_id).toBe('string'); + } + + // At least one fix should be attributed to the rule-engine rule, not + // solely the heuristic generator — that's the regression guard. + const hasRuleEngineAttribution = mpEmit.proposed_fixes.some( + f => f.rule_id && !f.rule_id.startsWith('heuristic:'), + ); + expect(hasRuleEngineAttribution).toBe(true); + }); +}); diff --git a/tests/integration/analytics/force-disable-check.test.js b/tests/integration/analytics/force-disable-check.test.js new file mode 100644 index 0000000..bdd4f52 --- /dev/null +++ b/tests/integration/analytics/force-disable-check.test.js @@ -0,0 +1,87 @@ +/** + * I4 — force-disable works on check names, not just rule_ids. + * + * An operator looking at a HARMFUL row in Rule Performance wants a + * one-click "stop emitting this diagnostic". Today's force-disable only + * gates rule_ids inside `runRules()`; structural checks (pos-supervisor:*) + * and LSP checks without a rule module never hit that path. The fix adds + * a filter in validate-code.js that drops diagnostics whose check name or + * rule_id appears in the force-disable set. + * + * This test exercises the end-to-end path: write the override file → boot + * the server → run validate_code → assert the suppressed diagnostic is + * absent and clearing the override restores it. + */ + +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { readFileSync } from 'node:fs'; +import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js'; +import { loadOverrides } from '../../../src/core/rule-overrides.js'; + +setDefaultTimeout(60_000); + +let server; +let proj; + +// A page with inline HTML and no partial renders → triggers +// pos-supervisor:HtmlInPage (our B-tier guard only suppresses when +// renders_used is non-empty, which this content isn't). +const FILE = 'app/views/pages/force-disable-test.liquid'; +const CONTENT = '---\nslug: force-disable-test\n---\n

hi

\n'; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +async function runValidate() { + return server.callTool('validate_code', { + file_path: FILE, + content: CONTENT, + mode: 'quick', + }); +} + +describe('force-disable on a check name', () => { + it('baseline: pos-supervisor:HtmlInPage fires on pure-HTML page', async () => { + const res = await runValidate(); + const all = [...(res.errors ?? []), ...(res.warnings ?? [])]; + expect(all.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true); + }); + + it('override suppresses the check; clearing it restores', async () => { + // Mirror the dashboard button path: POST to the endpoint, which writes + // the override file AND calls onOverridesChanged so the in-memory + // engine sees the new set without a restart. + const addResp = await fetch(server.baseUrl + '/api/engine/rule-overrides', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ action: 'force_disable', rule_id: 'pos-supervisor:HtmlInPage', reason: 'noisy on landing' }), + }); + const addBody = await addResp.json(); + expect(addResp.status).toBe(200); + expect(addBody.force_disable?.['pos-supervisor:HtmlInPage']).toBeDefined(); + // Sanity check that the file was written. + expect(loadOverrides(proj.dir).force_disable['pos-supervisor:HtmlInPage']).toBeDefined(); + + const suppressed = await runValidate(); + const suppressedAll = [...(suppressed.errors ?? []), ...(suppressed.warnings ?? [])]; + expect(suppressedAll.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(false); + + // Clear and re-run — the diagnostic returns. + const clearResp = await fetch(server.baseUrl + '/api/engine/rule-overrides', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ action: 'clear', rule_id: 'pos-supervisor:HtmlInPage' }), + }); + expect(clearResp.ok).toBe(true); + await clearResp.json(); + + const restored = await runValidate(); + const restoredAll = [...(restored.errors ?? []), ...(restored.warnings ?? [])]; + expect(restoredAll.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true); + }); +}); diff --git a/tests/integration/analytics/structural-rule-attribution.test.js b/tests/integration/analytics/structural-rule-attribution.test.js new file mode 100644 index 0000000..591cb7d --- /dev/null +++ b/tests/integration/analytics/structural-rule-attribution.test.js @@ -0,0 +1,76 @@ +/** + * Structural-warning → rule-engine bridge (2026-04-24 fix). + * + * Before the bridge, structural checks with rule modules (like + * `pos-supervisor:NonGetRenderingPage`) landed in analytics as + * `.unmatched` because their rule modules never got invoked — + * enrichAll runs before structural warnings are pushed. The bridge calls + * runRules() a second time on any diagnostic still missing rule_id. + * + * This test drives a real validate_code call that emits a structural + * warning and asserts the resulting validator_emit carries the rule's + * canonical rule_id, not the `.unmatched` fallback. + */ + +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { readFileSync, readdirSync, existsSync } from 'node:fs'; +import { join } from 'node:path'; +import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js'; + +setDefaultTimeout(30_000); + +let server; +let proj; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +function readValidatorEmits(projectDir) { + const sessionsDir = join(projectDir, '.pos-supervisor', 'sessions'); + if (!existsSync(sessionsDir)) return []; + const entries = readdirSync(sessionsDir, { withFileTypes: true }).filter(e => e.isDirectory()); + const out = []; + for (const entry of entries) { + const eventsPath = join(sessionsDir, entry.name, 'events.ndjson'); + if (!existsSync(eventsPath)) continue; + for (const line of readFileSync(eventsPath, 'utf-8').split('\n').filter(Boolean)) { + try { + const ev = JSON.parse(line); + if (ev.kind === 'validator_emit') out.push(ev); + } catch { /* skip */ } + } + } + return out; +} + +describe('structural rule attribution via bridge', () => { + // A page with method: post + HTML body — exactly the NonGetRenderingPage + // trigger. No slug under /api/, renders inline HTML and interpolates a + // variable so the UI-signal heuristics match. + it('NonGetRenderingPage lands as "NonGetRenderingPage.default", not ".unmatched"', async () => { + const FILE = 'app/views/pages/ngrp-bridge-test.liquid'; + const CONTENT = '---\nslug: ngrp-bridge-test\nmethod: post\nlayout: application\n---\n

form

\n{{ x }}\n'; + + await server.callTool('validate_code', { + file_path: FILE, + content: CONTENT, + mode: 'quick', + }); + + await new Promise(r => setTimeout(r, 100)); + + const emits = readValidatorEmits(proj.dir); + const ngrp = emits.find(e => e.file === FILE && e.check === 'pos-supervisor:NonGetRenderingPage'); + expect(ngrp).toBeDefined(); + expect(ngrp.hint_rule_id).toBe('NonGetRenderingPage.default'); + // Confidence also propagates through the bridge. + expect(ngrp.confidence).toBe(0.9); + }); +}); diff --git a/tests/integration/analytics/untracked.test.js b/tests/integration/analytics/untracked.test.js new file mode 100644 index 0000000..2afe42c --- /dev/null +++ b/tests/integration/analytics/untracked.test.js @@ -0,0 +1,135 @@ +/** + * A3 — `_source: 'dashboard_live'` must not pollute analytics. + * + * The dashboard Live Diagnostic Console calls `validate_code` against + * experimental snippets. Those calls are interactive debugging, not agent + * activity — they must not write tool_call events, validator_emit events, or + * session-state mutations to the analytics pipeline. + */ + +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { readFileSync, readdirSync, existsSync } from 'node:fs'; +import { join } from 'node:path'; +import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js'; + +setDefaultTimeout(30_000); + +let server; +let proj; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +function readSessionEvents(projectDir) { + const sessionsDir = join(projectDir, '.pos-supervisor', 'sessions'); + if (!existsSync(sessionsDir)) return []; + const entries = readdirSync(sessionsDir, { withFileTypes: true }) + .filter(e => e.isDirectory()); + const events = []; + for (const entry of entries) { + const eventsPath = join(sessionsDir, entry.name, 'events.ndjson'); + if (!existsSync(eventsPath)) continue; + const lines = readFileSync(eventsPath, 'utf-8').split('\n').filter(Boolean); + for (const line of lines) { + try { events.push(JSON.parse(line)); } catch { /* skip malformed */ } + } + } + return events; +} + +describe('_source: dashboard_live gates analytics writes (A3)', () => { + const SNIPPET_PATH = 'app/views/partials/__pos_live_console__.liquid'; + const SNIPPET_CONTENT = "{% assign foo = 'bar' %}\n

{{ foo }}

\n"; + + it('tracked validate_code writes a tool_call + validator_emit', async () => { + const before = readSessionEvents(proj.dir); + const beforeToolCalls = before.filter(e => e.kind === 'tool_call').length; + const beforeValidatorEmits = before.filter(e => e.kind === 'validator_emit').length; + + await server.callTool('validate_code', { + file_path: SNIPPET_PATH, + content: SNIPPET_CONTENT, + mode: 'quick', + }); + + // Give the writer a tick to flush. + await new Promise(r => setTimeout(r, 50)); + + const after = readSessionEvents(proj.dir); + const afterToolCalls = after.filter(e => e.kind === 'tool_call').length; + const afterValidatorEmits = after.filter(e => e.kind === 'validator_emit').length; + + expect(afterToolCalls).toBeGreaterThan(beforeToolCalls); + // UnusedAssign fires on the live-console snippet → at least one emit. + expect(afterValidatorEmits).toBeGreaterThan(beforeValidatorEmits); + }); + + it('untracked validate_code (dashboard_live) emits no tool_call or validator_emit', async () => { + const before = readSessionEvents(proj.dir); + const beforeToolCalls = before.filter(e => e.kind === 'tool_call').length; + const beforeValidatorEmits = before.filter(e => e.kind === 'validator_emit').length; + + await server.callTool('validate_code', { + file_path: SNIPPET_PATH, + content: SNIPPET_CONTENT, + mode: 'quick', + _source: 'dashboard_live', + }); + + await new Promise(r => setTimeout(r, 50)); + + const after = readSessionEvents(proj.dir); + const afterToolCalls = after.filter(e => e.kind === 'tool_call').length; + const afterValidatorEmits = after.filter(e => e.kind === 'validator_emit').length; + + expect(afterToolCalls).toBe(beforeToolCalls); + expect(afterValidatorEmits).toBe(beforeValidatorEmits); + }); + + it('untracked validate_code still returns diagnostics to the caller', async () => { + const result = await server.callTool('validate_code', { + file_path: SNIPPET_PATH, + content: SNIPPET_CONTENT, + mode: 'quick', + _source: 'dashboard_live', + }); + // The live console depends on this return path — untracked must not drop + // the response; only the analytics emission is gated. + expect(result).toBeDefined(); + expect(Array.isArray(result.errors)).toBe(true); + expect(Array.isArray(result.warnings)).toBe(true); + }); + + it('ctx.untracked is cleared after the call so subsequent tracked calls emit again', async () => { + // Run untracked first, then tracked — the second call must write events. + await server.callTool('validate_code', { + file_path: SNIPPET_PATH, + content: SNIPPET_CONTENT, + mode: 'quick', + _source: 'dashboard_live', + }); + + const before = readSessionEvents(proj.dir); + const beforeToolCalls = before.filter(e => e.kind === 'tool_call').length; + + await server.callTool('validate_code', { + file_path: SNIPPET_PATH, + content: SNIPPET_CONTENT, + mode: 'quick', + }); + + await new Promise(r => setTimeout(r, 50)); + + const after = readSessionEvents(proj.dir); + const afterToolCalls = after.filter(e => e.kind === 'tool_call').length; + + expect(afterToolCalls).toBeGreaterThan(beforeToolCalls); + }); +}); diff --git a/tests/unit/analytics-queries-k.test.js b/tests/unit/analytics-queries-k.test.js index 8c2ec32..155dab7 100644 --- a/tests/unit/analytics-queries-k.test.js +++ b/tests/unit/analytics-queries-k.test.js @@ -22,7 +22,7 @@ function emitDiag(store, { fp, template_fp, session_id, check, confidence, file kind: 'validator_emit', fp, template_fp, - file: file ?? 'app/views/pages/index.html.liquid', + file: file ?? 'test.liquid', hint_rule_id: check ?? null, confidence: confidence ?? null, proposed_fixes: [], @@ -139,6 +139,28 @@ describe('K3: confidenceCalibration', () => { const cal5 = confidenceCalibration(store, { buckets: 5 }); expect(cal5.length).toBeLessThanOrEqual(5); }); + + test('includes pipeline-stamped default confidences alongside rule-scored ones (A2)', () => { + const wid = store.insertWindow({ session_id: 's1', file: 'test.liquid', idx: 0, ts_start: '2026-04-17T10:00:00Z', ts_end: '2026-04-17T10:01:00Z' }); + + // Rule-scored high-confidence row — resolved. + emitDiag(store, { fp: 'rule-1', template_fp: 'tpl', session_id: 's1', check: 'X', confidence: 0.92 }); + store.insertOutcome({ fp: 'rule-1', window_id: wid, outcome: 'resolved' }); + + // Pipeline-default warning (0.7) — unchanged. Pre-A2 this row would have + // been excluded by the NULL filter in the query; post-A2 every surviving + // diagnostic carries a default, so the bucket sees it. + emitDiag(store, { fp: 'default-1', template_fp: 'tpl', session_id: 's1', check: 'X', confidence: 0.7 }); + store.insertOutcome({ fp: 'default-1', window_id: wid, outcome: 'unchanged' }); + + const cal = confidenceCalibration(store, { buckets: 10 }); + const totalSample = cal.reduce((sum, b) => sum + b.sample_size, 0); + expect(totalSample).toBe(2); + + const mid = cal.find(b => b.predicted >= 0.6 && b.predicted <= 0.8); + expect(mid?.sample_size).toBe(1); + expect(mid?.actual_resolution).toBe(0); + }); }); // ── K4: Fix Adoption Funnel ───────────────────────────────────────────── diff --git a/tests/unit/analytics-queries.test.js b/tests/unit/analytics-queries.test.js index 4e80bc5..6ceb943 100644 --- a/tests/unit/analytics-queries.test.js +++ b/tests/unit/analytics-queries.test.js @@ -6,6 +6,12 @@ import { toolSequenceBigrams, sessionSummaries, recommendations, + rulePerformance, + diagnosticJourney, + ruleDrilldown, + fixAdoptionFunnel, + adaptiveModeImpact, + fixRulePerformance, } from '../../src/core/analytics-queries.js'; import { rmSync } from 'node:fs'; import { join } from 'node:path'; @@ -244,3 +250,265 @@ describe('recommendations', () => { expect(recs).toHaveLength(0); }); }); + +// ── A4: rulePerformance (reporting view) ─────────────────────────────────── + +describe('rulePerformance', () => { + function emitWithRule(store, { fp, sessionId, check, ruleId, file, ts }) { + store.ingestEvent({ + v: 1, + session_id: sessionId, + ts: ts ?? '2026-04-17T10:00:00Z', + kind: 'validator_emit', + fp, + template_fp: `tpl-${fp}`, + file: file ?? 'app/views/pages/index.html.liquid', + check, + hint_rule_id: ruleId, + proposed_fixes: [], + }); + } + + test('returns empty when no rule_ids present', () => { + expect(rulePerformance(store)).toEqual([]); + }); + + test('default threshold of 1 surfaces single-emit rules', () => { + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'UnknownFilter', ruleId: 'UnknownFilter.typo' }); + const out = rulePerformance(store); + expect(out).toHaveLength(1); + expect(out[0].rule_id).toBe('UnknownFilter.typo'); + expect(out[0].emitted).toBe(1); + expect(out[0].unmatched).toBe(false); + }); + + test('includes `${check}.unmatched` fallback rule_ids (reporting coverage)', () => { + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'MissingPartial', ruleId: 'MissingPartial.unmatched' }); + emitWithRule(store, { fp: 'fp2', sessionId: 's1', check: 'MissingPartial', ruleId: 'MissingPartial.unmatched' }); + const out = rulePerformance(store); + const row = out.find(r => r.rule_id === 'MissingPartial.unmatched'); + expect(row).toBeDefined(); + expect(row.unmatched).toBe(true); + expect(row.emitted).toBe(2); + }); + + test('excludes rule_id "unknown" sentinel', () => { + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'X', ruleId: 'unknown' }); + expect(rulePerformance(store)).toEqual([]); + }); + + test('minEmitted filter honoured', () => { + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'A', ruleId: 'A.x' }); + emitWithRule(store, { fp: 'fp2', sessionId: 's1', check: 'B', ruleId: 'B.y' }); + emitWithRule(store, { fp: 'fp3', sessionId: 's1', check: 'B', ruleId: 'B.y' }); + const out = rulePerformance(store, { minEmitted: 2 }); + expect(out.map(r => r.rule_id)).toEqual(['B.y']); + }); + + test('EXISTS join does not inflate outcomes by per-emit diagnostic rows', () => { + // Post-A1: outcomes row per (session, file, fp). The same fp may appear + // many times in diagnostics (each validator_emit event). rulePerformance + // must count each outcome row once, not per emitting diagnostic. + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'UnknownFilter', ruleId: 'UnknownFilter.typo', ts: '2026-04-17T10:00:00Z' }); + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'UnknownFilter', ruleId: 'UnknownFilter.typo', ts: '2026-04-17T10:01:00Z' }); + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'UnknownFilter', ruleId: 'UnknownFilter.typo', ts: '2026-04-17T10:02:00Z' }); + + const windowId = store.insertWindow({ + session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 0, + ts_start: '2026-04-17T10:00:00Z', ts_end: '2026-04-17T10:03:00Z', + }); + store.insertOutcome({ fp: 'fp1', window_id: windowId, outcome: 'resolved', fix_applied: 'verbatim' }); + + const out = rulePerformance(store); + const row = out.find(r => r.rule_id === 'UnknownFilter.typo'); + expect(row.total_outcomes).toBe(1); + expect(row.resolved).toBe(1); + expect(row.adopted).toBe(1); + }); + + test('does not expose `disabled` flag (reporting is not a promotion decision)', () => { + emitWithRule(store, { fp: 'fp1', sessionId: 's1', check: 'A', ruleId: 'A.x' }); + const out = rulePerformance(store); + expect(out[0].disabled).toBeUndefined(); + }); +}); + +// ── hint_md_hash surfaced by journey + drilldown queries (Bug 2) ──────────── + +describe('journey + drilldown surface hint_md_hash', () => { + test('diagnosticJourney timeline entries carry hint_md_hash', () => { + store.ingestEvent({ + v: 1, session_id: 'j1', ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp: 'fp-j1', template_fp: 'tpl-j1', file: 'app/views/pages/a.liquid', + hint_rule_id: 'Check.rule', hint_md_hash: 'x'.repeat(64), + content_hash: 'y'.repeat(64), proposed_fixes: [], + }); + + const j = diagnosticJourney(store, 'tpl-j1'); + expect(j.timeline).toHaveLength(1); + expect(j.timeline[0].hint_md_hash).toBe('x'.repeat(64)); + }); + + test('ruleDrilldown samples carry hint_md_hash', () => { + store.ingestEvent({ + v: 1, session_id: 'd1', ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp: 'fp-d1', template_fp: 'tpl-d1', file: 'app/views/pages/b.liquid', + hint_rule_id: 'Check.rule', hint_md_hash: 'a'.repeat(64), + content_hash: 'b'.repeat(64), proposed_fixes: [], + }); + + const d = ruleDrilldown(store, 'Check.rule'); + expect(d.samples).toHaveLength(1); + expect(d.samples[0].hint_md_hash).toBe('a'.repeat(64)); + }); +}); + +// ── Funnel adoption counts (Bug 1) ────────────────────────────────────────── + +describe('fixAdoptionFunnel counts fix_applied correctly', () => { + test('picks up verbatim + partial + null adoption buckets', () => { + // Seed three fps, each with one diagnostic and one outcome that carries a + // fix_applied label. Post-Bug-1: classifyAndStoreWindows writes these; + // the query is read-only. + store.ingestEvent({ + v: 1, session_id: 'fa', ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp: 'v', template_fp: 'tpl-v', file: 'app/views/pages/v.liquid', + hint_rule_id: 'C.r', proposed_fixes: [], + }); + store.ingestEvent({ + v: 1, session_id: 'fa', ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp: 'p', template_fp: 'tpl-p', file: 'app/views/pages/p.liquid', + hint_rule_id: 'C.r', proposed_fixes: [], + }); + store.ingestEvent({ + v: 1, session_id: 'fa', ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp: 'n', template_fp: 'tpl-n', file: 'app/views/pages/n.liquid', + hint_rule_id: 'C.r', proposed_fixes: [], + }); + + const w1 = store.insertWindow({ session_id: 'fa', file: 'app/views/pages/v.liquid', idx: 0, ts_start: 'a', ts_end: 'b' }); + const w2 = store.insertWindow({ session_id: 'fa', file: 'app/views/pages/p.liquid', idx: 0, ts_start: 'a', ts_end: 'b' }); + const w3 = store.insertWindow({ session_id: 'fa', file: 'app/views/pages/n.liquid', idx: 0, ts_start: 'a', ts_end: 'b' }); + store.insertOutcome({ fp: 'v', window_id: w1, outcome: 'resolved', fix_applied: 'verbatim' }); + store.insertOutcome({ fp: 'p', window_id: w2, outcome: 'resolved', fix_applied: 'partial' }); + store.insertOutcome({ fp: 'n', window_id: w3, outcome: 'resolved', fix_applied: null }); + + const f = fixAdoptionFunnel(store); + expect(f.fix_adopted_verbatim).toBe(1); + expect(f.fix_adopted_partial).toBe(1); + expect(f.resolved).toBe(3); + }); +}); + +// ── Part G — adaptiveModeImpact window query ──────────────────────────────── + +describe('adaptiveModeImpact', () => { + const NOW = Date.now(); + function emitAt(msAgo, overrides = {}) { + const ts = new Date(NOW - msAgo).toISOString(); + store.ingestEvent({ + v: 1, session_id: 'ami', ts, kind: 'validator_emit', + fp: overrides.fp ?? 'fp-' + msAgo, + template_fp: 'tpl', file: 'app/views/pages/x.liquid', + hint_rule_id: overrides.rule ?? 'X.r', + confidence: overrides.confidence ?? 0.8, + proposed_fixes: [], + }); + } + + test('returns zero counts when window is empty', () => { + const r = adaptiveModeImpact(store, { windowMs: 60_000 }); + expect(r.emits_in_window).toBe(0); + expect(r.rule_matched_in_window).toBe(0); + expect(r.confidence.samples).toBe(0); + }); + + test('counts emits within the window + excludes .unmatched from rule_matched', () => { + emitAt(1_000, { fp: 'a', rule: 'X.r' }); + emitAt(2_000, { fp: 'b', rule: 'X.r' }); + emitAt(3_000, { fp: 'c', rule: 'Y.unmatched' }); + emitAt(3_600_001, { fp: 'old', rule: 'X.r' }); // outside 1h window + + const r = adaptiveModeImpact(store, { windowMs: 3_600_000 }); + expect(r.emits_in_window).toBe(3); + expect(r.rule_matched_in_window).toBe(2); // 'Y.unmatched' excluded + }); + + test('emits_by_rule groups per rule_id; caller intersects with disabled set', () => { + emitAt(1_000, { fp: 'a', rule: 'DisA' }); + emitAt(2_000, { fp: 'b', rule: 'DisA' }); + emitAt(2_000, { fp: 'c', rule: 'DisB' }); + + const r = adaptiveModeImpact(store, { windowMs: 60_000 }); + expect(r.emits_by_rule).toEqual({ DisA: 2, DisB: 1 }); + }); + + test('confidence stats reflect window-scoped emits only', () => { + emitAt(1_000, { fp: 'a', confidence: 0.9 }); + emitAt(2_000, { fp: 'b', confidence: 0.5 }); + + const r = adaptiveModeImpact(store, { windowMs: 60_000 }); + expect(r.confidence.samples).toBe(2); + expect(r.confidence.mean).toBeCloseTo(0.7, 2); + expect(r.confidence.min).toBe(0.5); + expect(r.confidence.max).toBe(0.9); + }); +}); + +// ── I1 — fixRulePerformance (attribution by proposed_fixes.rule_id) ───────── + +describe('fixRulePerformance', () => { + function emitWithFixes(sessionId, fp, fixes) { + store.ingestEvent({ + v: 1, session_id: sessionId, ts: '2026-04-17T10:00:00Z', kind: 'validator_emit', + fp, template_fp: 'tpl', file: 'app/views/pages/x.liquid', + hint_rule_id: 'Ignored', proposed_fixes: fixes, + }); + } + function outcome(fp, sessionId, out, fixApplied = null) { + const wid = store.insertWindow({ + session_id: sessionId, file: 'app/views/pages/x.liquid', idx: 0, + ts_start: 'a', ts_end: 'b', + }); + store.insertOutcome({ fp, window_id: wid, outcome: out, fix_applied: fixApplied }); + } + + test('returns empty when no rule_ids on fixes', () => { + emitWithFixes('s1', 'f', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: null }]); + expect(fixRulePerformance(store)).toEqual([]); + }); + + test('groups rule-engine vs heuristic under a `source` field', () => { + emitWithFixes('s1', 'f1', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'UnknownFilter.suggest_nearest' }]); + emitWithFixes('s1', 'f2', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:UnknownFilter.text_edit' }]); + const out = fixRulePerformance(store); + const rule = out.find(r => r.rule_id === 'UnknownFilter.suggest_nearest'); + const heur = out.find(r => r.rule_id === 'heuristic:UnknownFilter.text_edit'); + expect(rule?.source).toBe('rule'); + expect(heur?.source).toBe('heuristic'); + }); + + test('aggregates adoption + resolution per rule_id', () => { + emitWithFixes('s1', 'a', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:UnknownFilter.text_edit' }]); + emitWithFixes('s2', 'b', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:UnknownFilter.text_edit' }]); + emitWithFixes('s3', 'c', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:UnknownFilter.text_edit' }]); + outcome('a', 's1', 'resolved', 'verbatim'); + outcome('b', 's2', 'resolved', 'partial'); + outcome('c', 's3', 'unchanged', null); + + const r = fixRulePerformance(store).find(r => r.rule_id === 'heuristic:UnknownFilter.text_edit'); + expect(r.outcomes).toBe(3); + expect(r.adopted_verbatim).toBe(1); + expect(r.adopted_partial).toBe(1); + expect(r.adoption_rate).toBeCloseTo(2 / 3, 2); + expect(r.resolution_rate).toBeCloseTo(2 / 3, 2); + }); + + test('minProposed filter honoured', () => { + emitWithFixes('s1', 'a', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:Rare.text_edit' }]); + emitWithFixes('s2', 'b', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:Common.text_edit' }]); + emitWithFixes('s3', 'c', [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'heuristic:Common.text_edit' }]); + const out = fixRulePerformance(store, { minProposed: 2 }); + expect(out.map(r => r.rule_id)).toEqual(['heuristic:Common.text_edit']); + }); +}); diff --git a/tests/unit/analytics-store.test.js b/tests/unit/analytics-store.test.js index a34f884..217c14d 100644 --- a/tests/unit/analytics-store.test.js +++ b/tests/unit/analytics-store.test.js @@ -1,5 +1,7 @@ import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; import { openAnalyticsStore } from '../../src/core/analytics-store.js'; +import { openBlobStore } from '../../src/core/blob-store.js'; +import { fingerprint, templateOf } from '../../src/core/diagnostic-record.js'; import { mkdirSync, writeFileSync, rmSync } from 'node:fs'; import { join } from 'node:path'; import { tmpdir } from 'node:os'; @@ -77,13 +79,13 @@ afterEach(() => { describe('openAnalyticsStore', () => { test('creates database with schema', () => { const s = store.stats(); - expect(s.schema_version).toBe(1); + expect(s.schema_version).toBe(6); expect(s.events).toBe(0); expect(s.diagnostics).toBe(0); }); test('meta stores and retrieves values', () => { - expect(store.getMeta('schema_version')).toBe('1'); + expect(store.getMeta('schema_version')).toBe('6'); expect(store.getMeta('nonexistent')).toBeNull(); }); }); @@ -233,6 +235,54 @@ describe('insertWindow + insertOutcome', () => { expect(outcomes).toHaveLength(1); expect(outcomes[0].outcome).toBe('resolved'); expect(outcomes[0].fix_applied).toBe('verbatim'); + // Denormalized columns are derived from the window when not passed in. + expect(outcomes[0].session_id).toBe('s1'); + expect(outcomes[0].file).toBe('app/views/pages/index.html.liquid'); + }); + + test('dedupes on (session_id, file, fp) — terminal state wins', () => { + const w1 = store.insertWindow({ + session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 0, + ts_start: '2026-04-17T10:00:00Z', ts_end: '2026-04-17T10:01:00Z', + }); + const w2 = store.insertWindow({ + session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 1, + ts_start: '2026-04-17T10:01:00Z', ts_end: '2026-04-17T10:02:00Z', + }); + const w3 = store.insertWindow({ + session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 2, + ts_start: '2026-04-17T10:02:00Z', ts_end: '2026-04-17T10:03:00Z', + }); + + // Diagnostic flips: resolved in W1, regressed in W2, unchanged in W3. + store.insertOutcome({ fp: 'dup', window_id: w1, outcome: 'resolved' }); + store.insertOutcome({ fp: 'dup', window_id: w2, outcome: 'regressed' }); + store.insertOutcome({ fp: 'dup', window_id: w3, outcome: 'unchanged' }); + + const rows = store.query('SELECT * FROM outcomes WHERE fp = ?', ['dup']); + expect(rows).toHaveLength(1); + expect(rows[0].outcome).toBe('unchanged'); + expect(rows[0].window_id).toBe(w3); + }); + + test('different sessions with same fp stay separate', () => { + const wA = store.insertWindow({ + session_id: 'sA', file: 'app/views/pages/index.html.liquid', idx: 0, + ts_start: '2026-04-17T10:00:00Z', ts_end: '2026-04-17T10:01:00Z', + }); + const wB = store.insertWindow({ + session_id: 'sB', file: 'app/views/pages/index.html.liquid', idx: 0, + ts_start: '2026-04-17T11:00:00Z', ts_end: '2026-04-17T11:01:00Z', + }); + store.insertOutcome({ fp: 'shared', window_id: wA, outcome: 'resolved' }); + store.insertOutcome({ fp: 'shared', window_id: wB, outcome: 'regressed' }); + + const rows = store.query('SELECT session_id, outcome FROM outcomes WHERE fp = ? ORDER BY session_id', ['shared']); + expect(rows).toHaveLength(2); + expect(rows[0].session_id).toBe('sA'); + expect(rows[0].outcome).toBe('resolved'); + expect(rows[1].session_id).toBe('sB'); + expect(rows[1].outcome).toBe('regressed'); }); }); @@ -267,6 +317,44 @@ describe('query helpers', () => { }); }); +describe('outcome dedup invariants', () => { + test('one outcome per (session, file, fp) across N flip windows (terminal state wins)', () => { + const sessDir = tmpSessionDir(); + const diag = { check: 'MissingPartial', message: "Missing partial 'blog/card'", severity: 'error', line: 1 }; + // Diagnostic flips present/absent four times across five validate_code calls. + // Pre-A1 this yielded four outcome rows for the same fp (alternating + // resolved/regressed). Post-A1 there is exactly one row and it reflects + // the terminal state — the last window saw the diagnostic reappear. + const calls = [ + { ts: '2026-04-17T10:00:00.000Z', output: { errors: [diag], warnings: [] } }, + { ts: '2026-04-17T10:01:00.000Z', output: { errors: [], warnings: [] } }, + { ts: '2026-04-17T10:02:00.000Z', output: { errors: [diag], warnings: [] } }, + { ts: '2026-04-17T10:03:00.000Z', output: { errors: [], warnings: [] } }, + { ts: '2026-04-17T10:04:00.000Z', output: { errors: [diag], warnings: [] } }, + ].map(c => JSON.stringify({ + v: 1, session_id: 'test-session', kind: 'tool_call', tool: 'validate_code', + duration_ms: 80, success: true, + input: { file_path: 'app/views/pages/index.html.liquid', content: '{% render "blog/card" %}' }, + ts: c.ts, output: c.output, + })); + const lines = [makeServerStartLine(), ...calls].join('\n'); + writeFileSync(join(sessDir, 'events.ndjson'), lines + '\n'); + + store.ingestSession(sessDir); + + const outcomeRows = store.query(`SELECT outcome FROM outcomes`); + expect(outcomeRows).toHaveLength(1); + expect(outcomeRows[0].outcome).toBe('regressed'); + + // Invariant: resolved ≤ distinct fps with outcomes. Here resolved = 0. + const resolved = store.queryOne(`SELECT COUNT(*) AS c FROM outcomes WHERE outcome = 'resolved'`).c; + const uniqueFps = store.queryOne(`SELECT COUNT(DISTINCT fp) AS c FROM outcomes`).c; + expect(resolved).toBeLessThanOrEqual(uniqueFps); + + rmSync(sessDir, { recursive: true, force: true }); + }); +}); + describe('window classification via ingestion', () => { test('produces windows and outcomes from consecutive validate_code calls', () => { const sessDir = tmpSessionDir(); @@ -310,3 +398,242 @@ describe('real fixture ingestion', () => { expect(s.diagnostics).toBeGreaterThan(0); }); }); + +// ── proposed_fixes.rule_id persistence (I1) ───────────────────────────────── + +describe('proposed_fixes rule_id persistence', () => { + test('ingestValidatorEmit writes rule_id on every fix', () => { + store.ingestEvent({ + v: 1, session_id: 's1', ts: '2026-04-17T10:00:00Z', + kind: 'validator_emit', + fp: 'fp-i1', template_fp: 'tpl', file: 'app/views/pages/x.liquid', + proposed_fixes: [ + { range: null, new_text_hash: 'h1', kind: 'text_edit', rule_id: 'UnknownFilter.suggest_nearest' }, + { range: null, new_text_hash: 'h2', kind: 'text_edit', rule_id: 'heuristic:UnknownFilter.text_edit' }, + { range: null, new_text_hash: null, kind: 'guidance', rule_id: null }, + ], + }); + const rows = store.query(`SELECT kind, rule_id FROM proposed_fixes WHERE fp = 'fp-i1' ORDER BY rowid`); + expect(rows).toHaveLength(3); + expect(rows[0].rule_id).toBe('UnknownFilter.suggest_nearest'); + expect(rows[1].rule_id).toBe('heuristic:UnknownFilter.text_edit'); + expect(rows[2].rule_id).toBeNull(); + }); +}); + +// ── hint_md_hash persistence (Bug 2) ───────────────────────────────────────── + +describe('hint_md_hash persistence', () => { + test('ingestValidatorEmit writes hint_md_hash column', () => { + store.ingestEvent({ + v: 1, + session_id: 'hs', + ts: '2026-04-17T10:00:00.000Z', + kind: 'validator_emit', + fp: 'hfp', + template_fp: 'htpl', + file: 'app/views/pages/x.liquid', + hint_rule_id: 'X.rule', + hint_md_hash: 'deadbeef'.repeat(8), + content_hash: 'feedface'.repeat(8), + proposed_fixes: [], + }); + const row = store.queryOne( + `SELECT hint_md_hash FROM diagnostics WHERE fp = 'hfp'`, + ); + expect(row.hint_md_hash).toBe('deadbeef'.repeat(8)); + }); + + test('null hint_md_hash stays null', () => { + store.ingestEvent({ + v: 1, + session_id: 'hs2', + ts: '2026-04-17T10:00:00.000Z', + kind: 'validator_emit', + fp: 'hfp2', + file: 'app/views/pages/y.liquid', + content_hash: 'feedface'.repeat(8), + proposed_fixes: [], + }); + const row = store.queryOne( + `SELECT hint_md_hash FROM diagnostics WHERE fp = 'hfp2'`, + ); + expect(row.hint_md_hash).toBeNull(); + }); +}); + +// ── fix_applied classification via blobStore (Bug 1) ───────────────────────── + +describe('classifyAndStoreWindows: fix_applied classification', () => { + let blobDir; + let blobStore; + beforeEach(() => { + blobDir = join(tmpdir(), `pos-blobs-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`); + blobStore = openBlobStore(blobDir); + }); + afterEach(() => { + try { rmSync(blobDir, { recursive: true, force: true }); } catch {} + }); + + /** + * Write a session whose validator_emit fp matches the window classifier's + * computed fp. Both paths use fingerprint(check, file, messageTemplate) — + * diverging breaks the emit-index lookup. Helper shared by the test cases + * below so the fp calculation is visible in one place. + */ + function fpRow(sessDir, { sid, file, startContent, endContent, fixText, startTs, endTs, startDiag, endDiag }) { + const startHash = blobStore.put(startContent); + blobStore.put(endContent); + const fixHash = blobStore.put(fixText); + + const tmpl = templateOf(startDiag.check, startDiag.message); + const fp = fingerprint(startDiag.check, file, tmpl); + + const lines = [ + makeServerStartLine({ session_id: sid }), + JSON.stringify({ + v: 1, session_id: sid, ts: startTs, + kind: 'validator_emit', + fp, template_fp: 'tpl', file, + content_hash: startHash, + proposed_fixes: [{ range: null, new_text_hash: fixHash, kind: 'text_edit' }], + }), + JSON.stringify({ + v: 1, session_id: sid, ts: startTs, + kind: 'tool_call', tool: 'validate_code', duration_ms: 50, success: true, + input: { file_path: file, content: startContent }, + output: { errors: [startDiag], warnings: [] }, + }), + JSON.stringify({ + v: 1, session_id: sid, ts: endTs, + kind: 'tool_call', tool: 'validate_code', duration_ms: 45, success: true, + input: { file_path: file, content: endContent }, + output: { errors: endDiag ? [endDiag] : [], warnings: [] }, + }), + ].join('\n'); + writeFileSync(join(sessDir, 'events.ndjson'), lines + '\n'); + return { fp }; + } + + test('resolved + fix text present in end content → verbatim', () => { + const sessDir = tmpSessionDir(); + store.close(); + store = openAnalyticsStore(dbPath, { blobStore }); + + fpRow(sessDir, { + sid: 'sfa', file: 'app/views/pages/x.liquid', + startContent: "{{ 'hello' | capitalise }}", + endContent: "{{ 'hello' | capitalize }}", + fixText: 'capitalize', + startTs: '2026-04-17T10:00:01.000Z', endTs: '2026-04-17T10:01:00.000Z', + startDiag: { check: 'UnknownFilter', message: "Unknown filter 'capitalise'", severity: 'error', line: 1 }, + }); + + store.ingestSession(sessDir); + + const rows = store.query(`SELECT outcome, fix_applied FROM outcomes`); + expect(rows).toHaveLength(1); + expect(rows[0].outcome).toBe('resolved'); + expect(rows[0].fix_applied).toBe('verbatim'); + + rmSync(sessDir, { recursive: true, force: true }); + }); + + test('resolved + fix text NOT in end content → partial', () => { + const sessDir = tmpSessionDir(); + store.close(); + store = openAnalyticsStore(dbPath, { blobStore }); + + fpRow(sessDir, { + sid: 'sfa2', file: 'app/views/pages/y.liquid', + startContent: "{{ 'hello' | capitalise }}", + endContent: "{{ 'hello' | upcase }}", + fixText: 'capitalize', + startTs: '2026-04-17T10:00:01.000Z', endTs: '2026-04-17T10:01:00.000Z', + startDiag: { check: 'UnknownFilter', message: "Unknown filter 'capitalise'", severity: 'error', line: 1 }, + }); + + store.ingestSession(sessDir); + + const rows = store.query(`SELECT outcome, fix_applied FROM outcomes`); + expect(rows[0].outcome).toBe('resolved'); + expect(rows[0].fix_applied).toBe('partial'); + + rmSync(sessDir, { recursive: true, force: true }); + }); + + test('no blobStore → fix_applied stays null (backward compat)', () => { + const sessDir = tmpSessionDir(); + const lines = [ + makeServerStartLine(), + JSON.stringify({ + v: 1, session_id: 'test-session', ts: '2026-04-17T10:00:01.000Z', + kind: 'tool_call', tool: 'validate_code', duration_ms: 100, success: true, + input: { file_path: 'app/views/pages/z.liquid', content: "X" }, + output: { errors: [{ check: 'UnknownFilter', message: "Unknown filter 'x'", severity: 'error', line: 1 }], warnings: [] }, + }), + JSON.stringify({ + v: 1, session_id: 'test-session', ts: '2026-04-17T10:02:00.000Z', + kind: 'tool_call', tool: 'validate_code', duration_ms: 80, success: true, + input: { file_path: 'app/views/pages/z.liquid', content: "Y" }, + output: { errors: [], warnings: [] }, + }), + ].join('\n'); + writeFileSync(join(sessDir, 'events.ndjson'), lines + '\n'); + + store.ingestSession(sessDir); + const rows = store.query(`SELECT outcome, fix_applied FROM outcomes`); + expect(rows[0].outcome).toBe('resolved'); + expect(rows[0].fix_applied).toBeNull(); + + rmSync(sessDir, { recursive: true, force: true }); + }); + + test('regressed outcomes skip fix_applied classification', () => { + const sessDir = tmpSessionDir(); + store.close(); + store = openAnalyticsStore(dbPath, { blobStore }); + + const START = 'OLD'; + const END = 'NEW'; + const regressedDiag = { check: 'UnusedAssign', message: "Variable 'x' is assigned but never used", severity: 'warning', line: 1 }; + const file = 'app/views/pages/r.liquid'; + const fp = fingerprint(regressedDiag.check, file, templateOf(regressedDiag.check, regressedDiag.message)); + + const startHash = blobStore.put(START); + blobStore.put(END); + const fixHash = blobStore.put('IRRELEVANT'); + + const lines = [ + makeServerStartLine({ session_id: 'sr' }), + JSON.stringify({ + v: 1, session_id: 'sr', ts: '2026-04-17T10:01:00.000Z', + kind: 'validator_emit', + fp, template_fp: 'tpl', file, + content_hash: startHash, + proposed_fixes: [{ range: null, new_text_hash: fixHash, kind: 'text_edit' }], + }), + JSON.stringify({ + v: 1, session_id: 'sr', ts: '2026-04-17T10:00:00.000Z', + kind: 'tool_call', tool: 'validate_code', duration_ms: 50, success: true, + input: { file_path: file, content: START }, + output: { errors: [], warnings: [] }, + }), + JSON.stringify({ + v: 1, session_id: 'sr', ts: '2026-04-17T10:01:00.000Z', + kind: 'tool_call', tool: 'validate_code', duration_ms: 50, success: true, + input: { file_path: file, content: END }, + output: { errors: [regressedDiag], warnings: [] }, + }), + ].join('\n'); + writeFileSync(join(sessDir, 'events.ndjson'), lines + '\n'); + + store.ingestSession(sessDir); + + const rows = store.query(`SELECT outcome, fix_applied FROM outcomes WHERE fp = ?`, [fp]); + expect(rows[0].outcome).toBe('regressed'); + expect(rows[0].fix_applied).toBeNull(); + + rmSync(sessDir, { recursive: true, force: true }); + }); +}); diff --git a/tests/unit/case-base.test.js b/tests/unit/case-base.test.js index 64ba257..040c8fb 100644 --- a/tests/unit/case-base.test.js +++ b/tests/unit/case-base.test.js @@ -27,10 +27,14 @@ function seedStore(store, diagnostics, outcomes) { } for (const o of (outcomes.outcomes || [])) { + const wid = o.window_id ?? 1; + const w = (outcomes.windows || []).find(w => w.id === wid); + const session_id = o.session_id ?? w?.session_id ?? 'sess-1'; + const file = o.file ?? w?.file ?? 'test.liquid'; store.db.prepare(` - INSERT INTO outcomes (fp, window_id, outcome, fix_applied, collateral_added) - VALUES (?, ?, ?, ?, ?) - `).run(o.fp, o.window_id ?? 1, o.outcome, o.fix_applied ?? null, o.collateral_added ?? 0); + INSERT OR REPLACE INTO outcomes (fp, window_id, outcome, fix_applied, collateral_added, session_id, file) + VALUES (?, ?, ?, ?, ?, ?, ?) + `).run(o.fp, wid, o.outcome, o.fix_applied ?? null, o.collateral_added ?? 0, session_id, file); } } @@ -230,6 +234,30 @@ describe('Case base — F2: ruleScores', () => { const scores = ruleScores(store, { minEmitted: 5 }); expect(scores.length).toBe(0); }); + + test('excludes `${check}.unmatched` fallback rule_ids from promotion decisions (A4)', () => { + // Fallback rule_ids set by the diagnostic pipeline don't correspond to a + // registered rule — including them in ruleScores would feed noise into + // syncDisabledRules and probation. Promotion view must stay clean. + seedStore(store, + [ + { fp: 'u1', template_fp: 'tpl1', check_name: 'OrphanCheck', hint_rule_id: 'OrphanCheck.unmatched' }, + { fp: 'u2', template_fp: 'tpl1', check_name: 'OrphanCheck', hint_rule_id: 'OrphanCheck.unmatched' }, + { fp: 'u3', template_fp: 'tpl1', check_name: 'OrphanCheck', hint_rule_id: 'OrphanCheck.unmatched' }, + { fp: 'r1', template_fp: 'tpl1', check_name: 'RealCheck', hint_rule_id: 'RealCheck.real_rule' }, + ], + { + windows: [{ id: 1 }], + outcomes: [ + { fp: 'u1', outcome: 'resolved' }, + { fp: 'r1', outcome: 'resolved' }, + ], + } + ); + + const scores = ruleScores(store, { minEmitted: 1 }); + expect(scores.map(s => s.rule_id)).toEqual(['RealCheck.real_rule']); + }); }); describe('Case base — F2: scoreRule', () => { diff --git a/tests/unit/diagnostic-pipeline.test.js b/tests/unit/diagnostic-pipeline.test.js index 6972560..53e6726 100644 --- a/tests/unit/diagnostic-pipeline.test.js +++ b/tests/unit/diagnostic-pipeline.test.js @@ -7,6 +7,7 @@ import { suppressByPending, buildPendingPartialNames, buildPendingPageKeys, + stampDefaultsOn, } from '../../src/core/diagnostic-pipeline.js'; // ── helpers ────────────────────────────────────────────────────────────────── @@ -571,3 +572,116 @@ describe('verifyOrphanedPartialOnDisk via runDiagnosticPipeline', () => { expect(result.warnings).toHaveLength(1); }); }); + +// ── populateDefaultConfidence (A2) ────────────────────────────────────────── + +describe('diagnostic-pipeline: populateDefaultConfidence', () => { + it('stamps severity-based defaults when the rule engine left confidence unset', () => { + const result = makeResult( + [{ check: 'UndefinedObject', severity: 'error', message: 'foo' }], + [{ check: 'UnusedAssign', severity: 'warning', message: 'bar' }], + [{ check: 'InfoOnly', severity: 'info', message: 'baz' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.errors[0].confidence).toBe(0.9); + expect(result.warnings[0].confidence).toBe(0.7); + expect(result.infos[0].confidence).toBe(0.5); + }); + + it('does not overwrite a confidence value that the rule engine already set', () => { + const result = makeResult( + [{ check: 'UndefinedObject', severity: 'error', message: 'foo', confidence: 0.42 }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.errors[0].confidence).toBe(0.42); + }); + + it('stamps structural default for pos-supervisor: prefixed checks', () => { + const result = makeResult( + [], + [{ check: 'pos-supervisor:RemovedRender', severity: 'warning', message: 'removed' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.warnings[0].confidence).toBe(0.75); + }); + + it('runs after suppression — items removed from result never gain a default', () => { + const result = makeResult( + [], + [{ check: 'MissingPartial', severity: 'warning', message: "Missing partial 'notes/show'" }], + ); + runDiagnosticPipeline(result, { + filePath: 'app/views/pages/x.liquid', + content: '', + pendingFiles: ['app/views/partials/notes/show.liquid'], + }); + expect(result.warnings).toHaveLength(0); + }); + + it('falls back to warning-level confidence when severity is unset or unknown', () => { + const result = makeResult( + [], + [{ check: 'Weirdo', message: 'no severity' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.warnings[0].confidence).toBe(0.7); + }); + + // ── A4: rule_id fallback ─────────────────────────────────────────────── + it('stamps rule_id as `${check}.unmatched` when no rule fired', () => { + const result = makeResult( + [{ check: 'UndefinedObject', severity: 'error', message: 'foo' }], + [{ check: 'UnusedAssign', severity: 'warning', message: 'bar' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.errors[0].rule_id).toBe('UndefinedObject.unmatched'); + expect(result.warnings[0].rule_id).toBe('UnusedAssign.unmatched'); + }); + + it('preserves rule_id set by the rule engine', () => { + const result = makeResult( + [{ check: 'UndefinedObject', severity: 'error', message: 'foo', rule_id: 'UndefinedObject.context_user' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.errors[0].rule_id).toBe('UndefinedObject.context_user'); + }); + + it('falls back to `unknown.unmatched` when the diagnostic has no check name', () => { + const result = makeResult( + [], + [{ severity: 'warning', message: 'orphan' }], + ); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.warnings[0].rule_id).toBe('unknown.unmatched'); + }); +}); + +// ── stampDefaultsOn: post-pipeline stamping (confidence-bug fix) ───────────── + +describe('stampDefaultsOn: late-push diagnostics get default confidence', () => { + it('stamps diagnostics added AFTER runDiagnosticPipeline has already run', () => { + const result = makeResult([{ check: 'UnknownFilter', severity: 'error', message: 'x' }]); + runDiagnosticPipeline(result, { filePath: 'app/views/pages/x.liquid', content: '' }); + expect(result.errors[0].confidence).toBe(0.9); + + // Simulate a late push — e.g. structural-warnings / schema validator. + result.warnings.push({ + check: 'pos-supervisor:HtmlInPage', + severity: 'warning', + message: 'HTML in page', + }); + // Without the fix the late row would stay at confidence: null. + stampDefaultsOn(result); + expect(result.warnings[0].confidence).toBe(0.75); // structural default + expect(result.warnings[0].rule_id).toBe('pos-supervisor:HtmlInPage.unmatched'); + }); + + it('is idempotent — re-stamping does not overwrite existing values', () => { + const result = makeResult([ + { check: 'UnknownFilter', severity: 'error', message: 'x', confidence: 0.42, rule_id: 'UnknownFilter.typo' }, + ]); + stampDefaultsOn(result); + expect(result.errors[0].confidence).toBe(0.42); + expect(result.errors[0].rule_id).toBe('UnknownFilter.typo'); + }); +}); diff --git a/tests/unit/error-enricher-bridge.test.js b/tests/unit/error-enricher-bridge.test.js new file mode 100644 index 0000000..7257741 --- /dev/null +++ b/tests/unit/error-enricher-bridge.test.js @@ -0,0 +1,144 @@ +/** + * Bridge rules onto late-push diagnostics (2026-04-24 fix). + * + * Structural warnings, schema validators, diff-aware checks, and the + * new-partial caller check are pushed into `result.errors/warnings` AFTER + * `enrichAll` returns. Their rule modules never fire unless something runs + * the engine on them again. `bridgeRulesOntoUnattributed()` is that bridge. + */ + +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { + clearRules, registerRule, registerRules, updateForceOverrides, +} from '../../src/core/rules/engine.js'; +import { bridgeRulesOntoUnattributed } from '../../src/core/error-enricher.js'; +import { rules as NonGetRenderingPageRules } from '../../src/core/rules/NonGetRenderingPage.js'; +import { buildFactGraph } from '../../src/core/project-fact-graph.js'; + +function resetEngine() { + clearRules(); + updateForceOverrides({ force_enable: [], force_disable: [] }); +} + +beforeEach(resetEngine); +afterEach(resetEngine); + +function emptyProjectMap() { + return { pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [] }; +} + +const ctx = { + filePath: 'app/views/pages/x.liquid', + content: '', + factGraph: buildFactGraph(emptyProjectMap()), + filtersIndex: { loaded: true, lookup: () => null, closestMatch: () => null }, + objectsIndex: { loaded: true, lookup: () => null }, + tagsIndex: { isTag: () => false }, + schemaIndex: null, + analyticsStore: null, +}; + +describe('bridgeRulesOntoUnattributed', () => { + test('applies registered rule to a structural diagnostic with no prior rule_id', () => { + registerRules(NonGetRenderingPageRules); + const result = { + errors: [], + warnings: [{ + check: 'pos-supervisor:NonGetRenderingPage', + severity: 'warning', + message: 'method: post + renders HTML', + line: 1, + }], + infos: [], + }; + bridgeRulesOntoUnattributed(result, ctx); + const w = result.warnings[0]; + expect(w.rule_id).toBe('NonGetRenderingPage.default'); + expect(w.confidence).toBe(0.9); + expect(w.hint).toMatch(/method: post/i); + }); + + test('skips diagnostics that already carry a rule_id (idempotent)', () => { + registerRules(NonGetRenderingPageRules); + const result = { + errors: [], + warnings: [{ + check: 'pos-supervisor:NonGetRenderingPage', + severity: 'warning', + message: 'already stamped', + rule_id: 'explicit.override', + hint: 'explicit hint', + }], + infos: [], + }; + bridgeRulesOntoUnattributed(result, ctx); + // Pre-set rule_id preserved. + expect(result.warnings[0].rule_id).toBe('explicit.override'); + expect(result.warnings[0].hint).toBe('explicit hint'); + }); + + test('no-op when check has no registered rule module', () => { + // Rule module NOT registered. Diagnostic stays unattributed; stampDefaultsOn + // in the validate-code pipeline later fills in `.unmatched` fallback. + const result = { + errors: [], + warnings: [{ + check: 'pos-supervisor:SomeCheckWithNoRule', + severity: 'warning', + message: '...', + }], + infos: [], + }; + bridgeRulesOntoUnattributed(result, ctx); + expect(result.warnings[0].rule_id).toBeUndefined(); + }); + + test('no-op when factGraph is missing (guard against partial boot)', () => { + registerRules(NonGetRenderingPageRules); + const result = { + errors: [], + warnings: [{ check: 'pos-supervisor:NonGetRenderingPage', severity: 'warning', message: '...' }], + infos: [], + }; + bridgeRulesOntoUnattributed(result, { ...ctx, factGraph: null }); + expect(result.warnings[0].rule_id).toBeUndefined(); + }); + + test('applies to errors and infos too, not just warnings', () => { + registerRule({ + id: 'SampleRule.default', + check: 'SampleCheck', + priority: 100, + when: () => true, + apply: () => ({ rule_id: 'SampleRule.default', hint_md: 'hi', fixes: [], confidence: 0.5 }), + }); + const result = { + errors: [{ check: 'SampleCheck', severity: 'error', message: 'boom' }], + warnings: [{ check: 'SampleCheck', severity: 'warning', message: 'boom' }], + infos: [{ check: 'SampleCheck', severity: 'info', message: 'boom' }], + }; + bridgeRulesOntoUnattributed(result, ctx); + expect(result.errors[0].rule_id).toBe('SampleRule.default'); + expect(result.warnings[0].rule_id).toBe('SampleRule.default'); + expect(result.infos[0].rule_id).toBe('SampleRule.default'); + }); + + test('rule that throws does not crash the bridge (non-fatal)', () => { + registerRule({ + id: 'Explosive.default', + check: 'Explosive', + priority: 100, + when: () => true, + apply: () => { throw new Error('boom'); }, + }); + const result = { + errors: [], + warnings: [{ check: 'Explosive', severity: 'warning', message: '...' }], + infos: [], + }; + // Must not throw. + bridgeRulesOntoUnattributed(result, ctx); + // Diagnostic stays unattributed — safer than half-attributed. + expect(result.warnings[0].rule_id).toBeUndefined(); + }); +}); diff --git a/tests/unit/rule-engine-overrides.test.js b/tests/unit/rule-engine-overrides.test.js new file mode 100644 index 0000000..2ab5755 --- /dev/null +++ b/tests/unit/rule-engine-overrides.test.js @@ -0,0 +1,92 @@ +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { + registerRule, clearRules, runRules, + updateDisabledRules, updateForceOverrides, + setDisabledRuleDetails, getDisabledRuleDetails, + isCheckForceDisabled, +} from '../../src/core/rules/engine.js'; + +function makeRule(id, check, response) { + return { + id, check, priority: 10, + when: () => true, + apply: () => ({ rule_id: id, hint_md: response, fixes: [], confidence: 0.8 }), + }; +} + +// Reset module-level engine state so tests don't leak into other files +// (the engine registry + override sets are singletons; any assertion here +// that mutates them must tidy up, otherwise the next file runs with +// `_forceDisabled` still populated and legitimate rules silently skip). +function resetEngineState() { + clearRules(); + updateDisabledRules(null); + updateForceOverrides({ force_enable: [], force_disable: [] }); + setDisabledRuleDetails([]); +} + +beforeEach(resetEngineState); +afterEach(resetEngineState); + +describe('engine: force overrides', () => { + const diag = { check: 'UnknownFilter', message: "Unknown filter 'x'" }; + const facts = {}; + + test('force_disable beats normal enabled state', () => { + registerRule(makeRule('UnknownFilter.generic', 'UnknownFilter', 'hi')); + updateForceOverrides({ force_disable: ['UnknownFilter.generic'] }); + expect(runRules(diag, facts)).toBeNull(); + }); + + test('force_enable beats _disabledRules', () => { + registerRule(makeRule('UnknownFilter.generic', 'UnknownFilter', 'hi')); + updateDisabledRules(['UnknownFilter.generic']); + expect(runRules(diag, facts)).toBeNull(); // baseline: disabled + updateForceOverrides({ force_enable: ['UnknownFilter.generic'] }); + const r = runRules(diag, facts); + expect(r?.rule_id).toBe('UnknownFilter.generic'); + }); + + test('force_disable takes precedence over force_enable', () => { + registerRule(makeRule('UnknownFilter.generic', 'UnknownFilter', 'hi')); + updateForceOverrides({ + force_enable: ['UnknownFilter.generic'], + force_disable: ['UnknownFilter.generic'], + }); + expect(runRules(diag, facts)).toBeNull(); + }); + + test('getDisabledRuleDetails flags force_enabled rules', () => { + updateDisabledRules(['A.x']); + setDisabledRuleDetails([{ rule_id: 'A.x', effectiveness: 0.1, emitted: 10 }]); + updateForceOverrides({ force_enable: ['A.x'] }); + const details = getDisabledRuleDetails(); + expect(details).toHaveLength(1); + expect(details[0].force_enabled).toBe(true); + expect(details[0].effectiveness).toBe(0.1); + }); + + test('clearing overrides restores baseline behavior', () => { + registerRule(makeRule('UnknownFilter.generic', 'UnknownFilter', 'hi')); + updateForceOverrides({ force_disable: ['UnknownFilter.generic'] }); + expect(runRules(diag, facts)).toBeNull(); + updateForceOverrides({ force_enable: [], force_disable: [] }); + expect(runRules(diag, facts)?.rule_id).toBe('UnknownFilter.generic'); + }); +}); + +describe('engine: check-name force-disable', () => { + test('isCheckForceDisabled true only when name is in the set', () => { + updateForceOverrides({ force_disable: ['pos-supervisor:HtmlInPage'] }); + expect(isCheckForceDisabled('pos-supervisor:HtmlInPage')).toBe(true); + expect(isCheckForceDisabled('UnknownFilter')).toBe(false); + expect(isCheckForceDisabled(null)).toBe(false); + expect(isCheckForceDisabled(undefined)).toBe(false); + }); + + test('rule_ids and check names share the same force-disable set', () => { + updateForceOverrides({ force_disable: ['UnknownFilter.generic', 'pos-supervisor:HtmlInPage'] }); + expect(isCheckForceDisabled('UnknownFilter.generic')).toBe(true); + expect(isCheckForceDisabled('pos-supervisor:HtmlInPage')).toBe(true); + }); +}); diff --git a/tests/unit/rule-overrides.test.js b/tests/unit/rule-overrides.test.js new file mode 100644 index 0000000..3bad968 --- /dev/null +++ b/tests/unit/rule-overrides.test.js @@ -0,0 +1,79 @@ +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { mkdirSync, rmSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { + loadOverrides, saveOverrides, + addForceEnable, addForceDisable, removeOverride, + overrideSets, +} from '../../src/core/rule-overrides.js'; + +let projectDir; + +beforeEach(() => { + projectDir = join(tmpdir(), `pos-overrides-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`); + mkdirSync(projectDir, { recursive: true }); +}); + +afterEach(() => { + try { rmSync(projectDir, { recursive: true, force: true }); } catch {} +}); + +describe('rule-overrides: read/write', () => { + test('loadOverrides on missing file returns empty state', () => { + const s = loadOverrides(projectDir); + expect(s.force_enable).toEqual({}); + expect(s.force_disable).toEqual({}); + }); + + test('addForceEnable persists with ts + reason', () => { + const s = addForceEnable(projectDir, 'Foo.bar', 'testing'); + expect(s.force_enable['Foo.bar'].reason).toBe('testing'); + expect(typeof s.force_enable['Foo.bar'].ts).toBe('string'); + + // Round-trip: re-read from disk. + const loaded = loadOverrides(projectDir); + expect(loaded.force_enable['Foo.bar'].reason).toBe('testing'); + }); + + test('force_enable and force_disable are mutually exclusive', () => { + addForceDisable(projectDir, 'Foo.bar', 'kill'); + const s = addForceEnable(projectDir, 'Foo.bar', 'unkill'); + expect(s.force_enable['Foo.bar']).toBeDefined(); + expect(s.force_disable['Foo.bar']).toBeUndefined(); + }); + + test('removeOverride clears both kinds', () => { + addForceEnable(projectDir, 'A.x'); + addForceDisable(projectDir, 'B.y'); + const s = removeOverride(projectDir, 'A.x'); + expect(s.force_enable['A.x']).toBeUndefined(); + expect(s.force_disable['B.y']).toBeDefined(); + }); + + test('malformed JSON file → empty state (never throws)', () => { + const path = join(projectDir, '.pos-supervisor', 'rule-overrides.json'); + mkdirSync(join(projectDir, '.pos-supervisor'), { recursive: true }); + writeFileSync(path, '{not json'); + let logged = null; + const s = loadOverrides(projectDir, { log: (m) => { logged = m; } }); + expect(s.force_enable).toEqual({}); + expect(s.force_disable).toEqual({}); + expect(logged).toContain('failed to parse'); + }); + + test('force_enable or force_disable not object → empty state', () => { + const path = join(projectDir, '.pos-supervisor', 'rule-overrides.json'); + mkdirSync(join(projectDir, '.pos-supervisor'), { recursive: true }); + writeFileSync(path, JSON.stringify({ version: 1, force_enable: 'lol', force_disable: {} })); + const s = loadOverrides(projectDir); + expect(s.force_enable).toEqual({}); + }); + + test('overrideSets converts object maps to Sets', () => { + const state = { force_enable: { 'A.x': {} }, force_disable: { 'B.y': {} } }; + const { force_enable, force_disable } = overrideSets(state); + expect(force_enable.has('A.x')).toBe(true); + expect(force_disable.has('B.y')).toBe(true); + }); +}); diff --git a/tests/unit/rules/Tier1Rules.test.js b/tests/unit/rules/Tier1Rules.test.js new file mode 100644 index 0000000..e4be094 --- /dev/null +++ b/tests/unit/rules/Tier1Rules.test.js @@ -0,0 +1,79 @@ +/** + * Tier-1 rule modules — attribution + hint only. The text_edit fix is produced + * by fix-generator.js in full mode; these rules exist so the diagnostic gets + * a stable rule_id (instead of `.unmatched`) and a useful hint in the + * agent's response. + */ + +import { describe, test, expect, beforeEach } from 'bun:test'; +import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js'; +import { rules as ImgLazyLoadingRules } from '../../../src/core/rules/ImgLazyLoading.js'; +import { rules as ImgWidthAndHeightRules } from '../../../src/core/rules/ImgWidthAndHeight.js'; +import { rules as ConvertIncludeToRenderRules } from '../../../src/core/rules/ConvertIncludeToRender.js'; +import { rules as NonGetRenderingPageRules } from '../../../src/core/rules/NonGetRenderingPage.js'; + +describe('ImgLazyLoading.recommended', () => { + beforeEach(() => { clearRules(); registerRules(ImgLazyLoadingRules); }); + + test('fires on every ImgLazyLoading diagnostic with the canonical rule_id', () => { + const result = runRules( + { check: 'ImgLazyLoading', message: 'img without loading', line: 3, column: 2 }, + { graph: null }, + ); + expect(result).not.toBeNull(); + expect(result.rule_id).toBe('ImgLazyLoading.recommended'); + expect(result.confidence).toBe(0.9); + expect(result.hint_md).toMatch(/loading="lazy"/); + expect(result.fixes).toEqual([]); + }); + + test('returns null for other checks', () => { + expect(runRules({ check: 'UnknownFilter' }, { graph: null })).toBeNull(); + }); +}); + +describe('ImgWidthAndHeight.recommended', () => { + beforeEach(() => { clearRules(); registerRules(ImgWidthAndHeightRules); }); + + test('fires with canonical rule_id + CLS hint', () => { + const result = runRules( + { check: 'ImgWidthAndHeight', message: 'missing width/height', line: 5 }, + { graph: null }, + ); + expect(result.rule_id).toBe('ImgWidthAndHeight.recommended'); + expect(result.confidence).toBe(0.9); + expect(result.hint_md).toMatch(/width/i); + expect(result.hint_md).toMatch(/height/i); + }); +}); + +describe('ConvertIncludeToRender.default', () => { + beforeEach(() => { clearRules(); registerRules(ConvertIncludeToRenderRules); }); + + test('fires with canonical rule_id + explains render scope', () => { + const result = runRules( + { check: 'ConvertIncludeToRender', message: 'use render instead of include', line: 10 }, + { graph: null }, + ); + expect(result.rule_id).toBe('ConvertIncludeToRender.default'); + expect(result.confidence).toBe(0.9); + expect(result.hint_md).toMatch(/render/); + expect(result.hint_md).toMatch(/isolated scope/); + }); +}); + +describe('NonGetRenderingPage.default', () => { + beforeEach(() => { clearRules(); registerRules(NonGetRenderingPageRules); }); + + test('fires with canonical rule_id + action-oriented hint', () => { + const result = runRules( + { check: 'pos-supervisor:NonGetRenderingPage', message: 'page method: post + renders HTML' }, + { graph: null }, + ); + expect(result.rule_id).toBe('NonGetRenderingPage.default'); + expect(result.confidence).toBe(0.9); + expect(result.hint_md).toMatch(/method: post/i); + expect(result.hint_md).toMatch(/api/i); + expect(result.fixes).toEqual([]); + }); +}); diff --git a/tests/unit/structural-warnings.test.js b/tests/unit/structural-warnings.test.js index 9ace165..605765e 100644 --- a/tests/unit/structural-warnings.test.js +++ b/tests/unit/structural-warnings.test.js @@ -10,6 +10,7 @@ function getWarnings(content, filePath, existingChecks = new Set(), options = {} if (!ast) return []; const structural = extractAllFromAST(ast); const structuralObj = { + renders_used: structural.renders ?? [], tags_used: [...structural.tags], filters_used: [...structural.filters], doc_params: [...structural.docParams], @@ -56,6 +57,21 @@ describe('structural-warnings: HTML in pages', () => { expect(w.line).toBeGreaterThanOrEqual(0); expect(w.severity).toBe('warning'); }); + + // B-tier guard (2026-04-24): composite landing pages legitimately mix HTML + // wrappers with partial renders. Don't flag those — the check had 100% + // regression on exactly this pattern in the 2026-04-23 DEMO report. + it('does NOT warn for pages that render at least one partial (composite page)', () => { + const content = '---\nslug: index\n---\n
{% render "landing/hero" %}
'; + const warnings = getWarnings(content, '/project/app/views/pages/index.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:HtmlInPage')).toBe(false); + }); + + it('still warns for pure-HTML pages that do not render any partials', () => { + const content = '---\nslug: contact\n---\n
'; + const warnings = getWarnings(content, '/project/app/views/pages/contact.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:HtmlInPage')).toBe(true); + }); }); // ── GraphQL in partials ─────────────────────────────────────────────────── @@ -468,6 +484,54 @@ describe('structural-warnings: missing doc block', () => { // ── Method validation ───────────────────────────────────────────────────── +describe('structural-warnings: non-GET rendering page', () => { + // Landing-page mistake pattern the DEMO agent keeps repeating: + // `method: post` + HTML body → page 404s on browser GET. + it('warns when page has method: post and renders HTML content', () => { + const content = '---\nslug: contact\nmethod: post\nlayout: application\n---\n

Contact

\n
{{ foo }}
'; + const warnings = getWarnings(content, '/project/app/views/pages/contact.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(true); + }); + + it('warns when page has method: post and renders partials (composite landing)', () => { + const content = '---\nslug: index\nmethod: post\n---\n{% render "landing/hero" %}'; + const warnings = getWarnings(content, '/project/app/views/pages/index.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(true); + }); + + it('warns for put/delete/patch too', () => { + for (const method of ['put', 'delete', 'patch']) { + const content = `---\nslug: widget\nmethod: ${method}\n---\n
{{ x }}
`; + const warnings = getWarnings(content, '/project/app/views/pages/widget.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(true); + } + }); + + it('does NOT warn for API pages (slug under /api/)', () => { + const content = '---\nslug: api/contacts/create\nmethod: post\nformat: json\n---\n{{ r | json }}'; + const warnings = getWarnings(content, '/project/app/views/pages/api/contacts/create.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(false); + }); + + it('does NOT warn for JSON-only endpoints (no HTML, no layout, no partials, no output)', () => { + const content = '---\nslug: webhooks/stripe\nmethod: post\n---\n'; + const warnings = getWarnings(content, '/project/app/views/pages/webhooks/stripe.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(false); + }); + + it('does NOT warn for method: get', () => { + const content = '---\nslug: contact\nmethod: get\n---\n

Contact

'; + const warnings = getWarnings(content, '/project/app/views/pages/contact.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(false); + }); + + it('does NOT warn when method field is absent (default is get)', () => { + const content = '---\nslug: contact\n---\n

Contact

'; + const warnings = getWarnings(content, '/project/app/views/pages/contact.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:NonGetRenderingPage')).toBe(false); + }); +}); + describe('structural-warnings: method validation', () => { it('errors on uppercase POST', () => { const content = '---\nslug: test\nmethod: POST\n---\n{% assign x = 1 %}'; @@ -574,18 +638,33 @@ describe('structural-warnings: missing return in commands', () => { // ── Missing doc block in commands ───────────────────────────────────────── -describe('structural-warnings: missing doc block in commands', () => { - it('warns when command has no doc block', () => { +describe('structural-warnings: missing doc block in commands (B1.5 scope-out)', () => { + // Commands were dropped from MissingDocBlock after plan B1.5 — the check + // was 10% resolution / 40% regression on command files in production. + // Only partials still fire this warning. + it('does NOT warn when command has no doc block', () => { const content = '{% liquid\n assign object["id"] = 1\n return object\n%}'; const warnings = getWarnings(content, '/project/app/lib/commands/test/create.liquid'); - expect(warnings.some(w => w.check === 'pos-supervisor:MissingDocBlock')).toBe(true); + expect(warnings.some(w => w.check === 'pos-supervisor:MissingDocBlock')).toBe(false); }); - it('does not warn when command has doc block', () => { + it('does not warn when command has doc block either', () => { const content = '{% doc %}\n @param object {Hash}\n{% enddoc %}\n{% liquid\n return object\n%}'; const warnings = getWarnings(content, '/project/app/lib/commands/test/create.liquid'); expect(warnings.some(w => w.check === 'pos-supervisor:MissingDocBlock')).toBe(false); }); + + it('still warns for partials without doc block (regression guard)', () => { + const content = '
{{ x }}
'; + const warnings = getWarnings(content, '/project/app/views/partials/widget.html.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:MissingDocBlock')).toBe(true); + }); + + it('does not warn for queries without doc block', () => { + const content = '{% graphql res = "list_posts" %}{{ res | json }}'; + const warnings = getWarnings(content, '/project/app/lib/queries/list_posts.liquid'); + expect(warnings.some(w => w.check === 'pos-supervisor:MissingDocBlock')).toBe(false); + }); }); // ── Front matter key validation ─────────────────────────────────────────── diff --git a/tests/unit/window-classifier.test.js b/tests/unit/window-classifier.test.js index 03860b0..2a52014 100644 --- a/tests/unit/window-classifier.test.js +++ b/tests/unit/window-classifier.test.js @@ -4,6 +4,8 @@ import { classifyWindow, classifyFixAdoption, classifySession, + classifyWriteWindow, + extractWriteEvents, buildEmitIndex, computeCollateral, } from '../../src/core/window-classifier.js'; @@ -194,7 +196,81 @@ describe('classifyFixAdoption', () => { }); }); +function makeWriteEvent(relPath, ts) { + return { kind: 'fs_watcher_sync', rel_path: relPath, ts }; +} + +describe('extractWriteEvents', () => { + test('groups by rel_path', () => { + const events = [ + makeWriteEvent('app/views/pages/a.liquid', 't1'), + makeWriteEvent('app/views/pages/b.liquid', 't2'), + makeWriteEvent('app/views/pages/a.liquid', 't3'), + ]; + const writes = extractWriteEvents(events); + expect(writes.size).toBe(2); + expect(writes.get('app/views/pages/a.liquid')).toHaveLength(2); + expect(writes.get('app/views/pages/b.liquid')).toHaveLength(1); + }); + + test('returns empty map for no write events', () => { + const events = [makeVcCall()]; + expect(extractWriteEvents(events).size).toBe(0); + }); + + test('ignores events without rel_path', () => { + const events = [{ kind: 'fs_watcher_sync', path: '/abs/path/file.liquid', ts: 't1' }]; + expect(extractWriteEvents(events).size).toBe(0); + }); + + test('sorts events chronologically per file', () => { + const events = [ + makeWriteEvent('app/views/pages/a.liquid', '2026-04-17T10:02:00Z'), + makeWriteEvent('app/views/pages/a.liquid', '2026-04-17T10:01:00Z'), + ]; + const writes = extractWriteEvents(events); + const sorted = writes.get('app/views/pages/a.liquid'); + expect(sorted[0].ts).toBe('2026-04-17T10:01:00Z'); + expect(sorted[1].ts).toBe('2026-04-17T10:02:00Z'); + }); +}); + +describe('classifyWriteWindow', () => { + const FILE = 'app/views/pages/index.html.liquid'; + + test('produces write_unverified outcomes for all diagnostics', () => { + const vc = makeVcCall({ + ts: '2026-04-17T10:00:00Z', + output: { + errors: [ + makeDiag('MissingPartial', "Missing partial 'blog_posts/card'"), + makeDiag('UndefinedObject', "The object 'item' is undefined"), + ], + warnings: [], + }, + }); + const write = makeWriteEvent(FILE, '2026-04-17T10:01:00Z'); + const { window, outcomes } = classifyWriteWindow(vc, write); + + expect(outcomes).toHaveLength(2); + expect(outcomes.every(o => o.outcome === 'write_unverified')).toBe(true); + expect(window.closed_by).toBe('write'); + expect(window.is_draft).toBe(false); + expect(window.ts_end).toBe('2026-04-17T10:01:00Z'); + expect(window.content_hash_end).toBeNull(); + }); + + test('produces empty outcomes when validation was clean', () => { + const vc = makeVcCall({ output: { errors: [], warnings: [] } }); + const write = makeWriteEvent(FILE, 't2'); + const { outcomes } = classifyWriteWindow(vc, write); + expect(outcomes).toHaveLength(0); + }); +}); + describe('classifySession', () => { + const FILE = 'app/views/pages/index.html.liquid'; + test('builds windows for files with multiple calls', () => { const events = [ makeVcCall({ @@ -212,13 +288,13 @@ describe('classifySession', () => { expect(results[0].outcomes[0].outcome).toBe('resolved'); }); - test('skips files with only one call', () => { + test('skips files with only one call and no write event', () => { const events = [makeVcCall()]; const results = classifySession(events); expect(results).toHaveLength(0); }); - test('creates N-1 windows for N calls to same file', () => { + test('creates N-1 windows for N calls to same file (no writes)', () => { const events = [ makeVcCall({ ts: 't1', output: { errors: [], warnings: [] } }), makeVcCall({ ts: 't2', output: { errors: [], warnings: [] } }), @@ -229,6 +305,89 @@ describe('classifySession', () => { expect(results[0].window.idx).toBe(0); expect(results[1].window.idx).toBe(1); }); + + test('validate-to-validate windows are tagged is_draft=1 when no write between them', () => { + const events = [ + makeVcCall({ ts: '2026-04-17T10:00:00Z', output: { errors: [], warnings: [] } }), + makeVcCall({ ts: '2026-04-17T10:01:00Z', output: { errors: [], warnings: [] } }), + ]; + const results = classifySession(events); + expect(results[0].window.is_draft).toBe(1); + expect(results[0].window.closed_by).toBe('validate'); + }); + + test('validate-to-validate windows are tagged is_draft=0 when write falls between them', () => { + const events = [ + makeVcCall({ ts: '2026-04-17T10:00:00Z', output: { errors: [], warnings: [] } }), + makeWriteEvent(FILE, '2026-04-17T10:00:30Z'), + makeVcCall({ ts: '2026-04-17T10:01:00Z', output: { errors: [], warnings: [] } }), + ]; + const results = classifySession(events); + // One validate-to-validate window, no write after last validate + expect(results).toHaveLength(1); + expect(results[0].window.is_draft).toBe(0); + }); + + test('creates write-closed window for validate then write (no re-validate)', () => { + const events = [ + makeVcCall({ + ts: '2026-04-17T10:00:00Z', + output: { errors: [makeDiag('MissingPartial', "Missing partial 'x'")], warnings: [] }, + }), + makeWriteEvent(FILE, '2026-04-17T10:01:00Z'), + ]; + const results = classifySession(events); + expect(results).toHaveLength(1); + expect(results[0].window.closed_by).toBe('write'); + expect(results[0].outcomes[0].outcome).toBe('write_unverified'); + }); + + test('creates both validate-to-validate and write-closed window for full multi-draft sequence', () => { + // Draft 1 → Draft 2 → write + const events = [ + makeVcCall({ + ts: '2026-04-17T10:00:00Z', + output: { errors: [makeDiag('MissingPartial', "Missing partial 'x'")], warnings: [] }, + }), + makeVcCall({ + ts: '2026-04-17T10:01:00Z', + output: { errors: [makeDiag('MissingPartial', "Missing partial 'x'")], warnings: [] }, + }), + makeWriteEvent(FILE, '2026-04-17T10:02:00Z'), + ]; + const results = classifySession(events); + expect(results).toHaveLength(2); + + const validateWindow = results.find(r => r.window.closed_by === 'validate'); + const writeWindow = results.find(r => r.window.closed_by === 'write'); + + expect(validateWindow).toBeDefined(); + expect(validateWindow.window.is_draft).toBe(1); // no write between the two validates + expect(writeWindow).toBeDefined(); + expect(writeWindow.outcomes[0].outcome).toBe('write_unverified'); + }); + + test('proper workflow: validate → write → re-validate produces non-draft window + no write-closed', () => { + // The ideal agent workflow + const events = [ + makeVcCall({ + ts: '2026-04-17T10:00:00Z', + output: { errors: [makeDiag('MissingPartial', "Missing partial 'x'")], warnings: [] }, + }), + makeWriteEvent(FILE, '2026-04-17T10:01:00Z'), + makeVcCall({ + ts: '2026-04-17T10:02:00Z', + output: { errors: [], warnings: [] }, + }), + ]; + const results = classifySession(events); + // One validate-to-validate window (write falls between → is_draft=0 → resolved) + // No write after last validate → no write-closed window + expect(results).toHaveLength(1); + expect(results[0].window.is_draft).toBe(0); + expect(results[0].window.closed_by).toBe('validate'); + expect(results[0].outcomes[0].outcome).toBe('resolved'); + }); }); describe('buildEmitIndex', () => { From 02346fd6cb2d4c49fe2f1e50bd9d932650c18640 Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Mon, 27 Apr 2026 14:13:48 +0200 Subject: [PATCH 16/20] pos-cli 6.0.7 and new checks adaptation --- package-lock.json | 10 +- package.json | 2 +- src/core/diagnostic-pipeline.js | 49 +++ src/core/diagnostic-record.js | 49 +++ src/core/fix-generator.js | 93 +++--- src/core/module-scanner.js | 119 +++++-- src/core/rules/DuplicateFunctionArguments.js | 32 ++ src/core/rules/JsonLiteralQuoteStyle.js | 28 ++ src/core/rules/TranslationKeyExists.js | 45 ++- src/core/rules/ValidFrontmatter.js | 209 ++++++++++++ src/core/rules/index.js | 6 + src/data/hints/DuplicateFunctionArguments.md | 16 + src/data/hints/JsonLiteralQuoteStyle.md | 17 + src/data/hints/MissingPartial.md | 6 + src/data/hints/ValidFrontmatter.md | 27 ++ .../modules/common-styling/README.md | 143 ++++++--- .../modules/common-styling/advanced.md | 287 +++++++++-------- .../references/modules/common-styling/api.md | 243 ++++++++------ .../modules/common-styling/configuration.md | 210 +++++++----- .../modules/common-styling/gotchas.md | 238 +++++++------- .../modules/common-styling/patterns.md | 218 +++++++------ .../modules/common-styling/prerequisites.md | 114 +++++++ src/data/references/modules/core/README.md | 129 +++++--- src/data/references/modules/core/advanced.md | 214 +++++++------ src/data/references/modules/core/api.md | 299 +++++++----------- .../references/modules/core/configuration.md | 206 ++++++------ src/data/references/modules/core/gotchas.md | 142 +++++++-- src/data/references/modules/core/patterns.md | 178 ++++++----- src/data/references/modules/user/README.md | 93 +++--- src/data/references/modules/user/advanced.md | 216 ++++++------- src/data/references/modules/user/api.md | 124 +++++--- .../references/modules/user/configuration.md | 119 ++++--- src/data/references/modules/user/gotchas.md | 171 ++++++---- src/data/references/modules/user/patterns.md | 91 ++++-- .../references/modules/user/prerequisites.md | 154 +++++---- src/tools/analyze-project.js | 18 +- src/tools/module-info.js | 6 + src/tools/project-map.js | 1 + src/tools/validate-code.js | 63 +++- ...yze-project-lib-prefix.integration.test.js | 115 +++++++ .../pos-cli/translation-array-index.test.js | 102 ++++++ .../project-map.integration.test.js | 2 +- ...gnostic-pipeline-frontmatter-dedup.test.js | 171 ++++++++++ tests/unit/module-scanner-manifest.test.js | 233 ++++++++++++++ .../rules/DuplicateFunctionArguments.test.js | 38 +++ .../unit/rules/JsonLiteralQuoteStyle.test.js | 16 + tests/unit/rules/TranslationKeyExists.test.js | 66 ++++ tests/unit/rules/ValidFrontmatter.test.js | 141 +++++++++ tests/upstream/assign-syntax-coverage.test.js | 116 +++++++ tests/upstream/diagnostic-fingerprint.test.js | 105 ++++++ 50 files changed, 3901 insertions(+), 1589 deletions(-) create mode 100644 src/core/rules/DuplicateFunctionArguments.js create mode 100644 src/core/rules/JsonLiteralQuoteStyle.js create mode 100644 src/core/rules/ValidFrontmatter.js create mode 100644 src/data/hints/DuplicateFunctionArguments.md create mode 100644 src/data/hints/JsonLiteralQuoteStyle.md create mode 100644 src/data/hints/ValidFrontmatter.md create mode 100644 src/data/references/modules/common-styling/prerequisites.md create mode 100644 tests/integration/analyze-project-lib-prefix.integration.test.js create mode 100644 tests/integration/pos-cli/translation-array-index.test.js create mode 100644 tests/unit/diagnostic-pipeline-frontmatter-dedup.test.js create mode 100644 tests/unit/module-scanner-manifest.test.js create mode 100644 tests/unit/rules/DuplicateFunctionArguments.test.js create mode 100644 tests/unit/rules/JsonLiteralQuoteStyle.test.js create mode 100644 tests/unit/rules/ValidFrontmatter.test.js create mode 100644 tests/upstream/assign-syntax-coverage.test.js diff --git a/package-lock.json b/package-lock.json index d36b9a9..5613760 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,15 +1,15 @@ { "name": "@platformos/pos-supervisor", - "version": "0.1.0", + "version": "0.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@platformos/pos-supervisor", - "version": "0.1.0", + "version": "0.6.0", "dependencies": { "@modelcontextprotocol/sdk": "^1.29.0", - "@platformos/liquid-html-parser": "^0.0.11", + "@platformos/liquid-html-parser": "^0.0.17", "js-yaml": "^4.1.1", "zod": "^4.3.6" }, @@ -76,7 +76,9 @@ } }, "node_modules/@platformos/liquid-html-parser": { - "version": "0.0.11", + "version": "0.0.17", + "resolved": "https://registry.npmjs.org/@platformos/liquid-html-parser/-/liquid-html-parser-0.0.17.tgz", + "integrity": "sha512-JhoWMZahnq28kehdQBH8Up2jB4q+h0lTlFLsZDzm1YzzlAEYmYZXjn3CK1IZ8F2zEYCkVlEYKpNkERjZVPORCA==", "license": "MIT", "dependencies": { "line-column": "^1.0.2", diff --git a/package.json b/package.json index 4422968..7f3a7e9 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ }, "dependencies": { "@modelcontextprotocol/sdk": "^1.29.0", - "@platformos/liquid-html-parser": "^0.0.11", + "@platformos/liquid-html-parser": "^0.0.17", "js-yaml": "^4.1.1", "zod": "^4.3.6" }, diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js index 9a41407..2d65a83 100644 --- a/src/core/diagnostic-pipeline.js +++ b/src/core/diagnostic-pipeline.js @@ -1008,6 +1008,55 @@ export function stampDefaultsOn(result) { populateDefaultConfidence(result); } +/** + * Suppress upstream `ValidFrontmatter` diagnostics that overlap with our + * richer structural-check counterparts. pos-cli 6.0.7 added `ValidFrontmatter` + * which independently reports the same root causes as our existing + * `pos-supervisor:InvalidLayout` (missing layout file) and + * `pos-supervisor:InvalidFrontMatter` (unknown / misleading frontmatter keys). + * + * Our checks carry richer messages (named expected paths, deprecation + * guidance, fix templates) so we keep them and drop the upstream copy. + * Upstream `ValidFrontmatter` rows that don't share a line with one of our + * checks pass through untouched — they cover novel cases (deprecated + * `layout_name`, missing required fields per file type, invalid HTTP method + * enum, etc.) that our structural checks don't handle yet. + * + * Line-anchored: YAML frontmatter is one key per line, so a line collision + * between `ValidFrontmatter` and `pos-supervisor:InvalidLayout` / + * `pos-supervisor:InvalidFrontMatter` reliably indicates the same root cause. + * + * Idempotent. Pure. Safe to call after both diagnostic sources have pushed + * (i.e. after `generateStructuralWarnings`). + * + * @returns {number} count of suppressed diagnostics + */ +export function suppressUpstreamFrontmatterDup(result) { + const ourLines = new Set(); + for (const d of [...result.errors, ...result.warnings]) { + if (d.check === 'pos-supervisor:InvalidLayout' || + d.check === 'pos-supervisor:InvalidFrontMatter') { + ourLines.add(d.line); + } + } + if (ourLines.size === 0) return 0; + + const isRedundant = (d) => d.check === 'ValidFrontmatter' && ourLines.has(d.line); + const eRemoved = result.errors.filter(isRedundant).length; + const wRemoved = result.warnings.filter(isRedundant).length; + const removed = eRemoved + wRemoved; + if (removed === 0) return 0; + + result.errors = result.errors.filter(d => !isRedundant(d)); + result.warnings = result.warnings.filter(d => !isRedundant(d)); + result.infos.push({ + check: 'pos-supervisor:DuplicateFrontmatterCheck', + severity: 'info', + message: `Suppressed ${removed} ValidFrontmatter diagnostic(s) already covered by pos-supervisor structural check(s) (InvalidLayout / InvalidFrontMatter).`, + }); + return removed; +} + function hasRenderReferenceOnDisk(projectDir, partialName, selfPath) { const escaped = partialName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); const pattern = new RegExp(`['"]${escaped}['"]`); diff --git a/src/core/diagnostic-record.js b/src/core/diagnostic-record.js index 1eec7c6..a89fad2 100644 --- a/src/core/diagnostic-record.js +++ b/src/core/diagnostic-record.js @@ -228,6 +228,55 @@ const EXTRACTORS = Object.freeze({ return { is_function_call: /function call/i.test(message) ? 'true' : 'false' }; }, + ValidFrontmatter(message) { + // pos-cli 6.0.7 ships a single check that emits eight distinct shapes. + // We classify into a `category` so the rule engine can route to a + // category-specific hint without re-parsing the message itself. + // + // Categories: + // home_deprecated, missing_required, unknown_field, deprecated_field, + // invalid_enum, layout_false, layout_missing, association_missing, + // unknown (fallback — surfaces as `.unmatched` if it ever fires). + if (/'home\.html\.liquid' is deprecated/i.test(message)) { + return { category: 'home_deprecated' }; + } + let m = message.match(/^Missing required frontmatter field [`'"]([^`'"]+)[`'"] in (.+?) file$/); + if (m) return { category: 'missing_required', field: m[1], file_type: m[2] }; + m = message.match(/^Unknown frontmatter field [`'"]([^`'"]+)[`'"] in (.+?) file$/); + if (m) return { category: 'unknown_field', field: m[1], file_type: m[2] }; + if (/^`layout: false`/.test(message)) return { category: 'layout_false' }; + m = message.match(/^Layout [`'"]([^`'"]+)[`'"] does not exist$/); + if (m) return { category: 'layout_missing', layout: m[1] }; + m = message.match(/^Invalid value [`'"]([^`'"]+)[`'"] for [`'"]([^`'"]+)[`'"]\. Must be one of: (.+)$/); + if (m) return { category: 'invalid_enum', value: m[1], field: m[2], allowed: m[3] }; + m = message.match(/^[`'"]([^`'"]+)[`'"] is deprecated/); + if (m) return { category: 'deprecated_field', field: m[1] }; + if (/deprecated/i.test(message)) { + // Custom deprecation messages from per-field schemas — extract the first + // quoted token as a best-effort field hint. + const f = firstQuoted(message); + return f ? { category: 'deprecated_field', field: f } : { category: 'deprecated_field' }; + } + m = message.match(/^(.+?) [`'"]([^`'"]+)[`'"] does not exist$/); + if (m) return { category: 'association_missing', label: m[1], name: m[2] }; + return { category: 'unknown' }; + }, + + JsonLiteralQuoteStyle(_message) { + // Single-shot message — no params extracted. The category is implicit + // (always "single quote inside JSON literal"). Returning {} keeps the + // bag JSON-safe and lets the rule engine fire on `check` alone. + return {}; + }, + + DuplicateFunctionArguments(message) { + // "Duplicate argument 'x' in render tag for partial 'p'." + // "Duplicate argument 'x' in function tag for partial 'p'." + const m = message.match(/^Duplicate argument [`'"]([^`'"]+)[`'"] in (\w+) tag for partial [`'"]([^`'"]+)[`'"]\.?$/); + if (m) return { argument: m[1], tag_kind: m[2], partial: m[3] }; + return {}; + }, + GraphQLCheck(message) { const unused = message.match(/Variable\s+["']?\$(\w+)["']?\s+is never used/i); if (unused) return { category: 'unused_variable', variable: unused[1] }; diff --git a/src/core/fix-generator.js b/src/core/fix-generator.js index be73fa3..1084f66 100644 --- a/src/core/fix-generator.js +++ b/src/core/fix-generator.js @@ -1112,60 +1112,67 @@ function extractLayoutPath(message) { return `app/views/layouts/${match[1]}.html.liquid`; } +/** + * Heuristic fix for TranslationKeyExists. + * + * Scope (intentionally narrow): produce an actionable text_edit when the + * upstream LSP message contains a "Did you mean 'X'" suggestion AND we + * can locate the offending quoted key on the diagnostic's line. This is + * a complement to the rule-engine `TranslationKeyExists.suggest_nearest` + * — the rule emits guidance, the heuristic emits the diff. + * + * Cases the rule engine OWNS (heuristic must NOT duplicate): + * - `foo[0]` array-index misuse → `TranslationKeyExists.array_index_misuse` + * - generic Levenshtein guidance text → `TranslationKeyExists.suggest_nearest` + * + * Returning null means "no heuristic fix available" — the rule fix (if any) + * stands alone. This is the correct behavior when we can't produce an + * actionable edit. + */ function fixTranslationKeyExists(diagnostic, content) { const msg = diagnostic.message || ''; - // v0.3.3+ includes Levenshtein suggestion: "Did you mean 'correct.key'?" - const suggestMatch = msg.match(/[Dd]id you mean\s+['"`]([^'"`]+)['"`]/); - if (!suggestMatch) { - return { - type: 'guidance', - description: 'Translation key not found. Add it to app/translations/en.yml, or check for typos in the key name.', - }; - } - - const suggestedKey = suggestMatch[1]; - // Extract the wrong key from the message const wrongKeyMatch = msg.match(/['"`]([^'"`]+)['"`]/); const wrongKey = wrongKeyMatch ? wrongKeyMatch[1] : null; - if (!wrongKey || wrongKey === suggestedKey) { - return { - type: 'guidance', - description: `Did you mean \`${suggestedKey}\`? Fix the translation key.`, - }; - } - - // Find the wrong key string at the diagnostic position - const lines = content.split('\n'); - const line = lines[diagnostic.line]; - if (!line) { - return { - type: 'guidance', - description: `Replace translation key \`${wrongKey}\` with \`${suggestedKey}\`.`, - }; - } + // Array-index misuse is owned by the rule engine. Don't emit guidance + // here — it would duplicate (and risk diverging from) the rule's hint. + if (wrongKey && /\[\d+\]/.test(wrongKey)) return null; - // Look for the wrong key as a quoted string in the line - const keyPatterns = [`'${wrongKey}'`, `"${wrongKey}"`]; - for (const pattern of keyPatterns) { - const idx = line.indexOf(pattern); - if (idx >= 0) { - const quote = pattern[0]; - return { - type: 'text_edit', - range: { - start: { line: diagnostic.line, character: idx }, - end: { line: diagnostic.line, character: idx + pattern.length }, - }, - new_text: `${quote}${suggestedKey}${quote}`, - description: `Replace \`${wrongKey}\` with \`${suggestedKey}\``, - }; + // When the LSP message carries a "did you mean 'X'" suggestion AND we can + // locate the quoted key on the line, produce a text_edit. This is the + // ONLY case where the heuristic outranks rule guidance, because text_edits + // are actionable diffs the rule layer cannot produce. + const suggestMatch = msg.match(/[Dd]id you mean\s+['"`]([^'"`]+)['"`]/); + if (suggestMatch && wrongKey && wrongKey !== suggestMatch[1]) { + const suggestedKey = suggestMatch[1]; + const lines = content.split('\n'); + const line = lines[diagnostic.line]; + if (line) { + for (const pattern of [`'${wrongKey}'`, `"${wrongKey}"`]) { + const idx = line.indexOf(pattern); + if (idx >= 0) { + const quote = pattern[0]; + return { + type: 'text_edit', + range: { + start: { line: diagnostic.line, character: idx }, + end: { line: diagnostic.line, character: idx + pattern.length }, + }, + new_text: `${quote}${suggestedKey}${quote}`, + description: `Replace \`${wrongKey}\` with \`${suggestedKey}\``, + }; + } + } } } + // Generic guidance is the safety net for the case where the rule engine + // is not registered / facts are missing. In normal operation the merge + // loop in validate-code.js DROPS this guidance because the rule engine + // produces an attributed equivalent. See the precedence comment there. return { type: 'guidance', - description: `Replace translation key \`${wrongKey}\` with \`${suggestedKey}\`.`, + description: 'Translation key not found. Add it to app/translations/en.yml, or check for typos in the key name.', }; } diff --git a/src/core/module-scanner.js b/src/core/module-scanner.js index 87872ce..127a3ef 100644 --- a/src/core/module-scanner.js +++ b/src/core/module-scanner.js @@ -40,6 +40,8 @@ export async function scanModule(projectDir, moduleName) { display_name: metadata.name || moduleName, version: metadata.version || 'unknown', dependencies: metadata.dependencies || {}, + manifest_source: metadata.manifest_source ?? null, + ...(metadata.manifest_warnings ? { manifest_warnings: metadata.manifest_warnings } : {}), installed: true, ...apiSurface, schemas, @@ -71,6 +73,8 @@ export async function listModules(projectDir) { display_name: meta.name || entry.name, version: meta.version || 'unknown', dependencies: meta.dependencies || {}, + manifest_source: meta.manifest_source ?? null, + ...(meta.manifest_warnings ? { manifest_warnings: meta.manifest_warnings } : {}), }); } @@ -81,28 +85,107 @@ export async function listModules(projectDir) { } // ── Metadata scanning ──────────────────────────────────────────────────────── +// +// Precedence (most authoritative first): +// 1. `pos-module.json` — upstream platformOS module manifest. Source +// of truth for `version` and `dependencies`. +// 2. `template-values.json` — generated artifact emitted by +// `pos-cli modules version`. Mirrors +// pos-module.json but can drift if deps are +// added without re-running the version sync. +// 3. `package.json` — npm metadata. Its `version` reflects the +// npm-package layout, NOT the platformOS +// module version. Last-resort fallback. +// +// When both `pos-module.json` and `template-values.json` exist we run a drift +// check; any divergence in `version` or in the `dependencies` key set surfaces +// in `manifest_warnings` so module_info can flag it for the operator. + +async function readJsonOr(file) { + try { + return JSON.parse(await readFile(file, 'utf8')); + } catch { + return null; + } +} async function scanMetadata(moduleDir) { - // Try template-values.json first (platformOS module metadata) - const tvPath = join(moduleDir, 'template-values.json'); - try { - const content = await readFile(tvPath, 'utf8'); - return JSON.parse(content); - } catch {} + const posModule = await readJsonOr(join(moduleDir, 'pos-module.json')); + const templateValues = await readJsonOr(join(moduleDir, 'template-values.json')); + + let primary = null; + let source = null; + if (posModule) { + primary = posModule; + source = 'pos-module.json'; + } else if (templateValues) { + primary = templateValues; + source = 'template-values.json'; + } else { + const pkg = await readJsonOr(join(moduleDir, 'package.json')); + if (pkg) { + return { + name: pkg.name ?? null, + version: pkg.version ?? null, + dependencies: pkg.dependencies ?? {}, + manifest_source: 'package.json', + }; + } + return { manifest_source: null }; + } - // Fallback to package.json - const pkgPath = join(moduleDir, 'package.json'); - try { - const content = await readFile(pkgPath, 'utf8'); - const pkg = JSON.parse(content); - return { - name: pkg.name, - version: pkg.version, - dependencies: pkg.dependencies || {}, - }; - } catch {} + const out = { + name: primary.name ?? null, + version: primary.version ?? null, + dependencies: primary.dependencies ?? {}, + manifest_source: source, + }; + + if (posModule && templateValues) { + const warnings = detectManifestDrift(posModule, templateValues); + if (warnings.length > 0) out.manifest_warnings = warnings; + } + + return out; +} + +/** + * Compare `pos-module.json` and `template-values.json` and emit one warning per + * detected divergence. Used by scanMetadata to surface stale module-version + * sync state — the canonical fix is to re-run `pos-cli modules version `. + */ +function detectManifestDrift(posModule, templateValues) { + const warnings = []; + + if ((posModule.version ?? null) !== (templateValues.version ?? null)) { + warnings.push({ + kind: 'version_drift', + pos_module: posModule.version ?? null, + template_values: templateValues.version ?? null, + message: `pos-module.json (${posModule.version ?? 'null'}) and template-values.json (${templateValues.version ?? 'null'}) report different versions. pos-module.json wins. Re-run \`pos-cli modules version \` to sync.`, + }); + } + + const posDeps = posModule.dependencies ?? {}; + const tvDeps = templateValues.dependencies ?? {}; + const posKeys = Object.keys(posDeps); + const tvKeys = Object.keys(tvDeps); + const onlyPos = posKeys.filter(k => !(k in tvDeps)); + const onlyTv = tvKeys.filter(k => !(k in posDeps)); + + if (onlyPos.length > 0 || onlyTv.length > 0) { + warnings.push({ + kind: 'dependency_drift', + only_in_pos_module: onlyPos.sort(), + only_in_template_values: onlyTv.sort(), + message: [ + onlyPos.length > 0 ? `pos-module.json adds [${onlyPos.sort().join(', ')}]` : null, + onlyTv.length > 0 ? `template-values.json adds [${onlyTv.sort().join(', ')}]` : null, + ].filter(Boolean).join('; ') + '. pos-module.json wins. Re-run `pos-cli modules version ` to sync.', + }); + } - return {}; + return warnings; } // ── Public API surface ─────────────────────────────────────────────────────── diff --git a/src/core/rules/DuplicateFunctionArguments.js b/src/core/rules/DuplicateFunctionArguments.js new file mode 100644 index 0000000..6a85c2f --- /dev/null +++ b/src/core/rules/DuplicateFunctionArguments.js @@ -0,0 +1,32 @@ +/** + * DuplicateFunctionArguments rule — pos-cli 6.0.7 duplicate-arg detection. + * + * Upstream fires for both `{% render %}` and `{% function %}` when the same + * argument name appears twice in a single call. Liquid's last-key-wins + * semantics silently drops the first value, so the bug is usually a typo + * (two args meant to be different but typed the same). The rule attaches + * a rule_id and an action-oriented hint; upstream supplies the autofix. + */ + +export const rules = [ + { + id: 'DuplicateFunctionArguments.default', + check: 'DuplicateFunctionArguments', + priority: 100, + when: () => true, + apply: (diag) => { + const arg = diag.params?.argument ?? 'the duplicate argument'; + const tag = diag.params?.tag_kind ?? 'render'; + const partial = diag.params?.partial ?? '(unknown partial)'; + return { + rule_id: 'DuplicateFunctionArguments.default', + hint_md: `\`${arg}\` is passed twice to \`{% ${tag} '${partial}' %}\`. Liquid keeps the LAST occurrence and silently drops earlier ones — usually this is a typo (you meant two different keys). Decide: same value? delete one. Different values intended? rename one to its real key.`, + fixes: [{ + type: 'guidance', + description: `Open the \`{% ${tag} '${partial}' %}\` call. Remove the second \`${arg}: …\` occurrence, or rename it to whatever distinct key was meant.`, + }], + confidence: 0.9, + }; + }, + }, +]; diff --git a/src/core/rules/JsonLiteralQuoteStyle.js b/src/core/rules/JsonLiteralQuoteStyle.js new file mode 100644 index 0000000..3f06699 --- /dev/null +++ b/src/core/rules/JsonLiteralQuoteStyle.js @@ -0,0 +1,28 @@ +/** + * JsonLiteralQuoteStyle rule — pos-cli 6.0.7 inline JSON-literal grammar check. + * + * Upstream emits a single constant message when a single-quoted string appears + * inside a `{ … }` or `[ … ]` literal in `{% assign %}` / `{% return %}` / + * `{% function %}` arguments. The fix is mechanical: change the quotes to + * double quotes. The rule attaches a stable rule_id + a quote-swap-flavored + * hint; the upstream check itself ships an autofix corrector, so we don't + * duplicate the text_edit here. + */ + +export const rules = [ + { + id: 'JsonLiteralQuoteStyle.default', + check: 'JsonLiteralQuoteStyle', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'JsonLiteralQuoteStyle.default', + hint_md: 'String literals inside `{ … }` or `[ … ]` JSON literals must be double-quoted. Change the offending single quote to a double quote — the rest of the literal is fine. Liquid string assigns outside JSON literals (`{% assign x = \'hi\' %}`) are not affected.', + fixes: [{ + type: 'guidance', + description: "Replace the single-quoted string with a double-quoted equivalent. Example: `{ 'k': 'v' }` → `{ \"k\": \"v\" }`. The upstream check ships an autofix the agent can accept directly.", + }], + confidence: 0.95, + }), + }, +]; diff --git a/src/core/rules/TranslationKeyExists.js b/src/core/rules/TranslationKeyExists.js index 8b1528d..06f389f 100644 --- a/src/core/rules/TranslationKeyExists.js +++ b/src/core/rules/TranslationKeyExists.js @@ -1,14 +1,44 @@ /** * TranslationKeyExists rules — translation key not found. * - * Priority order: + * Priority order (first match wins): + * 5 — array_index_misuse: agent wrote `key[0]` / `key[1]` etc. + * platformOS translations cannot be subscripted with `[N]` — + * the modern pattern is `{% assign items = 'key' | t %}` then + * iterate with `{% for item in items %}`. Owns this case so the + * downstream Levenshtein rule never produces a misleading + * "did you mean en.key.items" suggestion. * 10 — suggest_nearest: key is close to an existing translation key - * 20 — create_key: suggest adding the key to translation file + * 20 — create_key: suggest adding the key to translation file */ import { translationKeysForLocale } from './queries.js'; import { nearestByLevenshtein } from './queries.js'; export const rules = [ + { + id: 'TranslationKeyExists.array_index_misuse', + check: 'TranslationKeyExists', + priority: 5, + when: (diag) => /\[\d+\]/.test(diag.params?.key ?? ''), + apply: (diag) => { + const key = diag.params.key; + const arrayKey = key.replace(/\[\d+\]/g, ''); + const guidance = + `Translation arrays don't support [index] syntax in Liquid. ` + + `Pass the full array, then iterate, for example: ` + + `{% assign items = '${arrayKey}' | t %}\n` + + `{% for item in items %}\n
  • {{ item }}
    • \n{% endfor %}`; + return { + rule_id: 'TranslationKeyExists.array_index_misuse', + hint_md: + `Translation key \`${key}\` uses \`[${key.match(/\[(\d+)\]/)[1]}]\` indexing — not supported. ` + + `Load the array with \`{% assign items = '${arrayKey}' | t %}\` and iterate with \`{% for %}\`.`, + fixes: [{ type: 'guidance', description: guidance }], + confidence: 0.9, + }; + }, + }, + { id: 'TranslationKeyExists.suggest_nearest', check: 'TranslationKeyExists', @@ -16,6 +46,9 @@ export const rules = [ when: (diag, facts) => { const key = diag.params?.key; if (!key) return false; + // Array-index misuse owns its own rule above; don't double-fire here + // (Levenshtein on `foo[0]` reliably finds a misleading parent key). + if (/\[\d+\]/.test(key)) return false; const keys = translationKeysForLocale(facts.graph, 'en'); return keys.length > 0; }, @@ -43,7 +76,13 @@ export const rules = [ id: 'TranslationKeyExists.create_key', check: 'TranslationKeyExists', priority: 20, - when: (diag) => !!diag.params?.key, + when: (diag) => { + const key = diag.params?.key; + if (!key) return false; + // Don't propose creating `foo[0]: TODO` — array_index_misuse owns this. + if (/\[\d+\]/.test(key)) return false; + return true; + }, apply: (diag) => { const key = diag.params.key; const parts = key.split('.'); diff --git a/src/core/rules/ValidFrontmatter.js b/src/core/rules/ValidFrontmatter.js new file mode 100644 index 0000000..91456a2 --- /dev/null +++ b/src/core/rules/ValidFrontmatter.js @@ -0,0 +1,209 @@ +/** + * ValidFrontmatter rules — pos-cli 6.0.7 frontmatter schema validator. + * + * The upstream check emits 8 distinct shapes (see EXTRACTORS in + * `core/diagnostic-record.js`). Each shape has a category-specific rule with + * an action-oriented hint. A `.fallback` rule covers the unknown shape so + * every emit gets a stable rule_id (no `.unmatched` rows in analytics). + * + * Phase 2 dedup (suppressUpstreamFrontmatterDup) drops the layout-missing and + * unknown-field shapes when they collide line-for-line with our richer + * pos-supervisor:* counterparts. Surviving emits are NOVEL coverage — + * the rules below add the missing context the agent needs to act. + * + * Confidence rationale: + * - Categorical rules where upstream gives an unambiguous fix (layout_false) + * ride at 0.9. + * - Categories that name a field but require human judgment (unknown_field, + * missing_required, invalid_enum, deprecated_field, association_missing, + * layout_missing, home_deprecated) ride at 0.85. + * - Fallback (unknown shape) rides at 0.5 — we don't know what fired, so + * the agent should not over-trust the hint. + */ + +const fmtField = (params) => + params?.field ? `\`${params.field}\`` : 'the offending key'; + +export const rules = [ + { + id: 'ValidFrontmatter.home_deprecated', + check: 'ValidFrontmatter', + priority: 10, + when: (diag) => diag.params?.category === 'home_deprecated', + apply: () => ({ + rule_id: 'ValidFrontmatter.home_deprecated', + hint_md: '`home.html.liquid` is deprecated. Rename to `index.html.liquid` to serve as the root page. Update any cross-references (renders, redirects) afterwards.', + fixes: [{ + type: 'guidance', + description: 'Rename the file from `home.html.liquid` to `index.html.liquid` and update any links/redirects pointing at it.', + }], + confidence: 0.85, + }), + }, + + { + id: 'ValidFrontmatter.missing_required', + check: 'ValidFrontmatter', + priority: 20, + when: (diag) => diag.params?.category === 'missing_required', + apply: (diag) => { + const field = fmtField(diag.params); + const fileType = diag.params.file_type ?? 'this'; + return { + rule_id: 'ValidFrontmatter.missing_required', + hint_md: `${field} is required for a ${fileType} file. Add it to the frontmatter block (between the leading and trailing \`---\`). \`scaffold\` produces the correct frontmatter for ${fileType} files when generating from a feature spec.`, + fixes: [{ + type: 'guidance', + description: `Add ${field} to the frontmatter. Refer to the ${fileType} domain guide via \`domain_guide\` for the expected shape.`, + }], + confidence: 0.85, + see_also: { + tool: 'domain_guide', + args: { domain: (diag.params.file_type ?? '').toLowerCase() || 'pages' }, + reason: `Required-field shapes vary per file type. domain_guide for ${fileType} lists the canonical frontmatter.`, + }, + }; + }, + }, + + { + id: 'ValidFrontmatter.unknown_field', + check: 'ValidFrontmatter', + priority: 30, + when: (diag) => diag.params?.category === 'unknown_field', + apply: (diag) => { + const field = fmtField(diag.params); + const fileType = diag.params.file_type ?? 'this'; + return { + rule_id: 'ValidFrontmatter.unknown_field', + hint_md: `${field} is not a valid frontmatter key for ${fileType} files. Common causes: typo (compare with the field list in \`domain_guide\`), wrong file type (this key may belong on a different file), or a leftover from another framework. Remove the key or move the value into the right shape.`, + fixes: [{ + type: 'guidance', + description: `Remove ${field} from the frontmatter, or replace it with the correct platformOS key. Consult \`domain_guide\` for the valid frontmatter keys per file type.`, + }], + confidence: 0.85, + }; + }, + }, + + { + id: 'ValidFrontmatter.deprecated_field', + check: 'ValidFrontmatter', + priority: 40, + when: (diag) => diag.params?.category === 'deprecated_field', + apply: (diag) => { + const field = fmtField(diag.params); + return { + rule_id: 'ValidFrontmatter.deprecated_field', + hint_md: `${field} is deprecated. The upstream message names the replacement (e.g. \`layout_name\` → \`layout\`, \`layout_path\` → \`layout\`). Rename in place; the value semantics are preserved.`, + fixes: [{ + type: 'guidance', + description: `Rename ${field} to its modern equivalent per the deprecation message. Don't remove the value — just change the key.`, + }], + confidence: 0.85, + }; + }, + }, + + { + id: 'ValidFrontmatter.invalid_enum', + check: 'ValidFrontmatter', + priority: 50, + when: (diag) => diag.params?.category === 'invalid_enum', + apply: (diag) => { + const field = fmtField(diag.params); + const value = diag.params.value ? `\`${diag.params.value}\`` : 'the supplied value'; + const allowed = diag.params.allowed ?? '(see message)'; + // Method comparison is case-insensitive in the upstream check, so an + // uppercase HTTP method like `POST` will be flagged. Surface the + // canonical lowercase variant when the value matches an allowed token + // case-insensitively. + const lowerValue = (diag.params.value ?? '').toLowerCase(); + const allowedTokens = allowed.split(/[,\s]+/).map(s => s.trim()).filter(Boolean); + const canonical = allowedTokens.find(t => t.toLowerCase() === lowerValue); + const guidance = canonical + ? `Replace ${value} with \`${canonical}\` — same value, just the canonical case.` + : `Replace ${value} with one of: ${allowed}.`; + return { + rule_id: 'ValidFrontmatter.invalid_enum', + hint_md: `${value} is not a valid value for ${field}. Allowed: ${allowed}. ${guidance}`, + fixes: [{ + type: 'guidance', + description: guidance, + }], + confidence: 0.85, + }; + }, + }, + + { + id: 'ValidFrontmatter.layout_false', + check: 'ValidFrontmatter', + priority: 60, + when: (diag) => diag.params?.category === 'layout_false', + apply: () => ({ + rule_id: 'ValidFrontmatter.layout_false', + hint_md: '`layout: false` does NOT disable the layout — YAML parses `false` as boolean and platformOS falls back to the default layout. Use `layout: \'\'` (empty string) to render the page without a layout.', + fixes: [{ + type: 'guidance', + description: "Replace `layout: false` with `layout: ''` (empty single-quoted string). This is the supported way to opt out of layout rendering.", + }], + confidence: 0.9, + }), + }, + + { + id: 'ValidFrontmatter.layout_missing', + check: 'ValidFrontmatter', + priority: 70, + when: (diag) => diag.params?.category === 'layout_missing', + apply: (diag) => { + const layout = diag.params.layout ?? '(unnamed)'; + const expected = layout.startsWith('modules/') + ? `modules/${layout.split('/')[1]}/public/views/layouts/${layout.split('/').slice(2).join('/')}.{html.,}liquid` + : `app/views/layouts/${layout}.{html.,}liquid`; + return { + rule_id: 'ValidFrontmatter.layout_missing', + hint_md: `Layout \`${layout}\` was not found. Expected file path: \`${expected}\`. Either fix the layout name in the frontmatter or create the layout file (must include \`{{ content_for_layout }}\` to render the page body).`, + fixes: [{ + type: 'guidance', + description: `Verify spelling against existing layouts in \`app/views/layouts/\` (or modules' layout directories) — call \`project_map\` to enumerate. If the layout truly is missing, create it with a \`{{ content_for_layout }}\` placeholder.`, + }], + confidence: 0.85, + }; + }, + }, + + { + id: 'ValidFrontmatter.association_missing', + check: 'ValidFrontmatter', + priority: 80, + when: (diag) => diag.params?.category === 'association_missing', + apply: (diag) => { + const label = diag.params.label ?? 'Referenced file'; + const name = diag.params.name ?? '(unnamed)'; + return { + rule_id: 'ValidFrontmatter.association_missing', + hint_md: `${label} \`${name}\` does not exist. Authorization policies live under \`app/authorization_policies/\`; email/SMS/API-call notifications under their respective dirs. Create the referenced file or fix the reference.`, + fixes: [{ + type: 'guidance', + description: `Verify the file path matches an existing ${label.toLowerCase()} or scaffold the missing one. Call \`project_map\` to see what exists.`, + }], + confidence: 0.85, + }; + }, + }, + + { + id: 'ValidFrontmatter.fallback', + check: 'ValidFrontmatter', + priority: 100, + when: () => true, + apply: () => ({ + rule_id: 'ValidFrontmatter.fallback', + hint_md: 'Frontmatter validation failed. Read the upstream message — it names the field and shape problem. Reference: `domain_guide` per file type, or `scaffold` to regenerate canonical frontmatter.', + fixes: [], + confidence: 0.5, + }), + }, +]; diff --git a/src/core/rules/index.js b/src/core/rules/index.js index ab2c8bd..5769df3 100644 --- a/src/core/rules/index.js +++ b/src/core/rules/index.js @@ -21,6 +21,9 @@ import { rules as ImgLazyLoadingRules } from './ImgLazyLoading.js'; import { rules as ImgWidthAndHeightRules } from './ImgWidthAndHeight.js'; import { rules as ConvertIncludeToRenderRules } from './ConvertIncludeToRender.js'; import { rules as NonGetRenderingPageRules } from './NonGetRenderingPage.js'; +import { rules as ValidFrontmatterRules } from './ValidFrontmatter.js'; +import { rules as JsonLiteralQuoteStyleRules } from './JsonLiteralQuoteStyle.js'; +import { rules as DuplicateFunctionArgumentsRules } from './DuplicateFunctionArguments.js'; const ALL_RULE_MODULES = [ MissingPartialRules, @@ -36,6 +39,9 @@ const ALL_RULE_MODULES = [ ImgWidthAndHeightRules, ConvertIncludeToRenderRules, NonGetRenderingPageRules, + ValidFrontmatterRules, + JsonLiteralQuoteStyleRules, + DuplicateFunctionArgumentsRules, ]; let _loaded = false; diff --git a/src/data/hints/DuplicateFunctionArguments.md b/src/data/hints/DuplicateFunctionArguments.md new file mode 100644 index 0000000..96e47c1 --- /dev/null +++ b/src/data/hints/DuplicateFunctionArguments.md @@ -0,0 +1,16 @@ +Argument `{{argument}}` passed twice to `{% {{tag_kind}} '{{partial}}' %}`. + +STEP 1 — Read the call site. + Open the file at the reported line and locate the `{% {{tag_kind}} %}` call. Two instances of `{{argument}}: …` exist in the same call. + +STEP 2 — Decide which value to keep. + → If the values are identical, delete one of the duplicates. + → If the values differ, this is a logic bug: the second one wins (Liquid's last-key-wins semantics) but the intent was likely to pass two DIFFERENT named args. Rename one to its real name. + +STEP 3 — Apply the fix. + Remove the duplicate occurrence of `{{argument}}: …`. Trailing comma may need cleaning up. + +STEP 4 — Re-validate. + CALL `validate_code` on this file after the fix. + +Why it matters: silently dropping the first value usually masks an off-by-one mistake (two args meant to be different but typed the same). The check fires when the partial-call signature has the duplicate, regardless of value. diff --git a/src/data/hints/JsonLiteralQuoteStyle.md b/src/data/hints/JsonLiteralQuoteStyle.md new file mode 100644 index 0000000..0fbdfde --- /dev/null +++ b/src/data/hints/JsonLiteralQuoteStyle.md @@ -0,0 +1,17 @@ +Inline object/array literals must use double-quoted strings. + +STEP 1 — Identify the literal. + Object literal: `{% assign x = { 'k': 'v' } %}` — both keys and values use single quotes. + Array literal: `{% assign xs = [ 'a', 'b' ] %}` — string items use single quotes. + +STEP 2 — Apply the fix. + → Change every single-quoted string inside `{ … }` and `[ … ]` to double-quoted: + BEFORE: `{% assign hash = { 'name': 'value' } %}` + AFTER: `{% assign hash = { "name": "value" } %}` + → JSON literal grammar requires double quotes — single quotes break round-trip with `{% parse_json %}` consumers and external JSON tooling. + +STEP 3 — Re-validate. + CALL `validate_code` on this file after the fix. + FAIL → another single-quoted string remains nested inside the literal; widen the search to nested `{ … }` / `[ … ]`. + +Note: this rule does NOT apply to plain Liquid string assignments (`{% assign x = 'hello' %}` is fine). Only inline JSON-shaped literals require double quotes. diff --git a/src/data/hints/MissingPartial.md b/src/data/hints/MissingPartial.md index fe56ab6..4cdc82d 100644 --- a/src/data/hints/MissingPartial.md +++ b/src/data/hints/MissingPartial.md @@ -8,6 +8,12 @@ STEP 1 — Determine the right fix. → GOTO STEP 2 to create the missing file. Output came from scaffold: → Check scaffold output for exact path, do NOT rename scaffold files. + For a simple form submission consider using the core module's execute helper directly: + ```liquid + function object = 'modules/core/commands/execute', mutation_name: 'contact_submissions/create', selection: 'record_create', object: object + ``` + Use this when: single mutation, simple create/update/delete. + Create custom command at app/lib/commands/ when: complex logic, multiple steps, reusable across pages. STEP 2 — Create '{{name}}'. Path: {{create_path}} diff --git a/src/data/hints/ValidFrontmatter.md b/src/data/hints/ValidFrontmatter.md new file mode 100644 index 0000000..2d806e0 --- /dev/null +++ b/src/data/hints/ValidFrontmatter.md @@ -0,0 +1,27 @@ +{{#if category}}{{category_summary}}{{else}}Frontmatter validation failed.{{/if}} + +STEP 1 — Identify the category. + missing_required → A required key for this file type is absent. + unknown_field → A key not recognized for this file type. + deprecated_field → Key is recognized but deprecated. Replace per the schema's deprecation guidance. + invalid_enum → Value is outside the allowed set for this key. + layout_missing → Layout file referenced does not exist on disk. + layout_false → `layout: false` falls back to the default layout (silent footgun). + association_missing → Auth policy / notification reference does not match a file. + home_deprecated → File should be renamed `index.html.liquid`. + +STEP 2 — Apply the fix. +{{#if field}} + Field involved: `{{field}}`{{#if file_type}} (file type: {{file_type}}){{/if}}. +{{/if}} +{{#if category_fix}} + → {{category_fix}} +{{else}} + → Read the message; the upstream check names the exact field and the expected shape. +{{/if}} + +STEP 3 — Re-validate. + CALL `validate_code` on this file after the fix. + FAIL → review the file's domain conventions via `domain_guide`. + +Frontmatter rules vary per file type (Page, Layout, Partial, Form Configuration, Email, SMS, API Call, Authorization Policy, Migration). When in doubt: scaffold tool generates correct frontmatter for the chosen file type. diff --git a/src/data/references/modules/common-styling/README.md b/src/data/references/modules/common-styling/README.md index cc54911..06ea954 100644 --- a/src/data/references/modules/common-styling/README.md +++ b/src/data/references/modules/common-styling/README.md @@ -1,8 +1,11 @@ # pos-module-common-styling -Provides the CSS framework and UI components for platformOS projects. NEVER use Tailwind, Bootstrap, or custom frameworks. +The CSS framework + reusable partials for platformOS projects. NEVER mix +in Tailwind, Bootstrap, or custom CSS frameworks — they fight the shipped +design tokens. -**Required module** — must be installed in every project. +**Required module** on most apps. Compatible with pos-cli 6.0.7+ +(modernized canonical class names + partial names). ## Install @@ -10,74 +13,120 @@ Provides the CSS framework and UI components for platformOS projects. NEVER use pos-cli modules install common-styling ``` -## Documentation - -Full docs: https://github.com/Platform-OS/pos-module-common-styling - ## Setup -### In layout `` ```liquid +{% comment %} layout {% endcomment %} {% render 'modules/common-styling/init' %} ``` -### On `` tag ```html + ``` +For dark mode, add `pos-theme-darkEnabled` (auto via system preference) or +`pos-theme-dark` (forced). + +```html + +``` + ## Viewing Components -Browse available components at `/style-guide` on your instance. +Browse the shipped style guide at `/style-guide` on any instance with this +module installed. Each section is a self-contained partial under +`views/partials/style-guide/` — copy what you need. -## CSS Classes +## Class Inventory (live) -All classes use the `pos-*` prefix: +The full `pos-*` class set is scanned from disk: -```html -
    -
    -

    Title

    -

    Content

    -
    -
    - - - - - -
    Success message
    -
    Error message
    +```bash +node -e "import('./src/core/module-scanner.js').then(m => m.scanModule('.', 'common-styling').then(r => console.log(r.css_classes.filter(c => c.startsWith('pos-')).join('\\n'))))" ``` -## Key Components +This is the source of truth. `module_info(name: 'common-styling')` exposes +the same list. Class families: + +- **Buttons**: `pos-button`, `pos-button-primary`, `pos-button-small`, + `pos-button-label`. There is NO `pos-button-secondary` / `-danger` / + `-success` / `-large` — those don't ship. +- **Cards**: `pos-card`, `pos-card-content`, `pos-card-content-footer`, + `pos-card-content-image`, `pos-card-content-title`, + `pos-card-content-permalink`, `pos-card-highlighted`. Card sub-elements + are NOT BEM (`__`); they're hyphenated. +- **Alerts**: rendered via the `content/alert` partial; classes are + `pos-card-alert` + `pos-card-alert-{success|error|warning|info}`. There + is NO `pos-alert-*` family — those names will NOT match any shipped CSS. +- **Toasts**: `pos-toast`, `pos-toast-error`, `pos-toast-success`, + `pos-toast-info`, `pos-toast-loading`, `pos-toast-close`, `pos-toasts` + (container). +- **Forms**: `pos-form`, `pos-form-input`, `pos-form-error`, + `pos-form-fieldset`, `pos-form-checkbox`, `pos-form-multiselect-*`, + `pos-form-password-*`, `pos-form-actions`. Use the partials under + `partials/forms/` for the multi-element widgets (multiselect, password, + upload). +- **Avatars**: `pos-avatar`, `pos-avatar-{xs,sm,md,lg,xl,2xl,3xl}`. +- **Tags**: `pos-tag`, `pos-tag-confirmation`, `pos-tag-warning`, + `pos-tag-important`, `pos-tag-interactive`, `pos-tags-list`. +- **Dialog**: `pos-dialog`, `pos-dialog-actions`, `pos-dialog-close`, + `pos-dialog-header`, `pos-dialog-header-simple`. +- **Headings**: `pos-heading-{1..6}`, `pos-heading-with-action`. +- **Utility (semantic)**: `pos-gap-{section-section, text-text, …}`, + `pos-mt-{...}`. NOT Tailwind-style atomic utilities — there's NO + `pos-p-1`, `pos-mt-2`, `pos-text-primary`, `pos-flex`, `pos-grid`. + +## Key Components (renderable partials) -### Pagination ```liquid -{% render 'modules/common-styling/pagination', - total_pages: result.records.total_pages -%} -``` +{% comment %} content card {% endcomment %} +{% render 'modules/common-styling/content/card', + url: '/posts/1', title: 'Title', + content: 'Description', highlighted: true %} -### File Upload -```liquid +{% comment %} alert box {% endcomment %} +{% render 'modules/common-styling/content/alert', + type: 'success', content: 'Saved.' %} + +{% comment %} dialog (modal) {% endcomment %} +{% render 'modules/common-styling/content/dialog', ... %} + +{% comment %} navigation widget {% endcomment %} +{% render 'modules/common-styling/navigation/collapsible', ... %} + +{% comment %} form bits {% endcomment %} +{% render 'modules/common-styling/forms/error_list', errors: errors, name: 'title' %} +{% render 'modules/common-styling/forms/multiselect', ... %} +{% render 'modules/common-styling/forms/password', ... %} {% render 'modules/common-styling/forms/upload', - id: 'image', - presigned_upload: presigned, - name: 'image', - allowed_file_types: ['image/*'], - max_number_of_files: 5 -%} -``` + id: 'image', name: 'image', + presigned_upload: presigned, allowed_file_types: ['image/*'] %} -### Toasts (Flash Messages) -```liquid -{% render 'modules/common-styling/toasts', params: flash %} +{% comment %} user-facing avatar / card {% endcomment %} +{% render 'modules/common-styling/user/avatar', user: user %} +{% render 'modules/common-styling/user/card', user: user %} ``` ## Rules -- NEVER use Tailwind, Bootstrap, or custom CSS frameworks -- Always use `pos-*` prefixed classes -- Check `/style-guide` on your instance for available components -- Initialize with `{% render 'modules/common-styling/init' %}` in layout head +- ALWAYS initialize with `{% render 'modules/common-styling/init' %}` in + the layout ``. +- ALWAYS set `class="pos-app"` on the `` tag. +- NEVER mix in Tailwind / Bootstrap / utility-class generators. +- VERIFY every class name against the live scan — fictional names produce + unstyled output. +- Prefer `{% render '...partial' %}` over hand-composed class soup; the + shipped partials encode the design-system semantics correctly. +- For alerts use `content/alert`, NOT `pos-alert-*` classes (which don't + exist). + +## See Also + +- [Configuration](configuration.md) — full setup +- [API](api.md) — class families + render-able partials +- [Patterns](patterns.md) — common compositions +- [Gotchas](gotchas.md) — fictional-class footguns +- [Advanced](advanced.md) — overrides, dark-mode, custom themes +- [Prerequisites](prerequisites.md) — required app-side setup +- Live class set: `module_info(name: 'common-styling')` diff --git a/src/data/references/modules/common-styling/advanced.md b/src/data/references/modules/common-styling/advanced.md index 253d7e5..c4b95e4 100644 --- a/src/data/references/modules/common-styling/advanced.md +++ b/src/data/references/modules/common-styling/advanced.md @@ -1,203 +1,202 @@ -# modules/common-styling - Advanced Customization +# modules/common-styling — Advanced Topics -## Theme Customization +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). -### CSS Variables Override -Customize the theme by overriding CSS variables: +## Theme Customization via Design Tokens -```scss -// app/assets/styles/theme.scss +The shipped CSS exposes its tokens as CSS custom properties under +`pos-config.css`. Override them in your own stylesheet to retheme without +touching the framework files: -:root { - --pos-primary-color: #007bff; - --pos-secondary-color: #6c757d; - --pos-success-color: #28a745; - --pos-danger-color: #dc3545; - --pos-warning-color: #ffc107; - --pos-info-color: #17a2b8; - - --pos-text-primary: #212529; - --pos-text-secondary: #6c757d; - --pos-background: #ffffff; - --pos-border-color: #dee2e6; +```css +/* app/assets/theme.css — loaded AFTER common-styling/init */ +.pos-app { + --pos-color-light-page-background: #fafafa; + --pos-color-light-content-background: #fff; + --pos-color-light-content-text: #1a1a1a; + --pos-color-light-frame: #e6e6e6; + --pos-gap-section-section: 3rem; + --pos-gap-text-text: 0.75rem; } ``` -### Dark Mode Support -Implement dark mode: +Wire it up: -```scss -@media (prefers-color-scheme: dark) { - :root { - --pos-background: #1e1e1e; - --pos-text-primary: #f0f0f0; - --pos-text-secondary: #b0b0b0; - --pos-border-color: #404040; - } -} +```liquid +{% comment %} layout , AFTER init render {% endcomment %} +{% render 'modules/common-styling/init' %} + ``` -## Custom Component Creation +Inspect `modules/common-styling/public/assets/style/pos-config.css` for +the canonical token list. Token naming pattern: +`--pos-color-{light|dark}-{role}` and `--pos-gap-{from-to}`. -### Extending Components -Create custom component variants: +## Dark Mode -```scss -// app/assets/styles/components.scss +The module ships dark variants automatically. Activate at the root: -.pos-btn-custom { - @extend .pos-btn; - background-color: var(--pos-primary-color); - text-transform: uppercase; - letter-spacing: 1px; +```html + + - &:hover { - background-color: darken(var(--pos-primary-color), 10%); - } + + +``` + +The dark token set parallels the light one (`--pos-color-dark-*`). To +customize dark, override in a `[class~="pos-theme-dark"]` selector: + +```css +.pos-theme-dark.pos-app, +.pos-theme-darkEnabled.pos-app { + --pos-color-dark-content-background: #0d0d0d; + --pos-color-dark-content-text: #e8e8e8; } ``` -### Component Mixins -Create reusable component styles: +## Extending Components -```scss -@mixin pos-card-variant($bg, $border) { - background-color: $bg; - border-color: $border; +Components are partials + classes. To add a custom variant: - .pos-card-header { - background-color: darken($bg, 5%); - } +1. Add a class in your own stylesheet that COMPOSES the shipped class. +2. Use it alongside the shipped class. + +```css +.my-button-cta { + /* compose with pos-button rules */ + background: linear-gradient(135deg, + var(--pos-color-light-accent), + var(--pos-color-light-accent-2)); + letter-spacing: 0.05em; + text-transform: uppercase; } +``` + +```html + +``` + +Don't use SCSS `@extend .pos-button` — the shipped CSS is plain CSS with +custom properties; SCSS toolchain may not be present. + +## Custom Card Variants + +Cards are render-with-extras: pass extra classes to the partial via +your own wrapper: + +```liquid +
    + {% render 'modules/common-styling/content/card', + url: '/x', title: 'Premium', content: '…', + highlighted: true %} +
    +``` -.pos-card-premium { - @include pos-card-variant(#f8f9fa, #dee2e6); +```css +.my-premium-card .pos-card-content-title { + color: var(--pos-color-light-accent); +} +.my-premium-card .pos-card-highlighted { + border-color: var(--pos-color-light-accent); } ``` ## Responsive Design -### Breakpoints -Use framework breakpoints: - -```scss -$pos-breakpoints: ( - 'xs': 0, - 'sm': 576px, - 'md': 768px, - 'lg': 992px, - 'xl': 1200px -); +The module ships NO grid system, NO `pos-col-*`. Use native CSS Grid / +Flexbox with media queries: +```css +.section-grid { + display: grid; + grid-template-columns: 1fr; + gap: var(--pos-gap-section-section); +} @media (min-width: 768px) { - .pos-col-md-6 { - width: 50%; + .section-grid { + grid-template-columns: 2fr 1fr; } } ``` -### Mobile-First Approach -Build mobile designs first: - ```html -
    -
    -
    - Full width on mobile, half on desktop -
    -
    - Full width on mobile, half on desktop -
    -
    +
    + {% render 'modules/common-styling/content/card', ... %} + {% render 'modules/common-styling/content/card', ... %}
    ``` -## Animation and Transitions +## Transitions / Animations -### Add Smooth Transitions -```scss -.pos-btn { - transition: all 0.3s ease-in-out; -} +The shipped CSS already animates a few interactive components (toasts on +load/unload, dialogs, collapsibles). For your own work: +```css .pos-card { - transition: box-shadow 0.3s ease; - - &:hover { - box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); - } + transition: box-shadow 200ms ease; +} +.pos-card:hover { + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08); } ``` -### Custom Animations -```scss -@keyframes slideIn { - from { - opacity: 0; - transform: translateX(-20px); - } - to { - opacity: 1; - transform: translateX(0); - } -} +Toast load animation: -.pos-alert { - animation: slideIn 0.3s ease-out; -} +```html +
    Saved.
    + +
    Saved.
    ``` -## Performance Optimization +## Overriding Shipped Partials -### Lazy Loading Components -Load heavy components on demand: +To customize a shipped partial, copy it to the module-override mirror: -```liquid -{% if show_advanced_ui %} - {% render 'modules/common-styling/components/advanced-form' %} -{% endif %} +```bash +mkdir -p app/modules/common-styling/public/views/partials/content +cp modules/common-styling/public/views/partials/content/card.liquid \ + app/modules/common-styling/public/views/partials/content/card.liquid ``` -### CSS Purging -Remove unused styles in production: - -```yml -# platformos.yml -assets: - purge: - enabled: true - content: - - 'app/**/*.liquid' - - 'app/**/*.html' -``` +Edit the override; it shadows the shipped one when consumers `{% render +'modules/common-styling/content/card', ... %}`. -## Accessibility Enhancements +Keep overrides minimal — diverging too far from upstream means painful +module upgrades. -### Semantic HTML -Use proper semantic elements: +## Asset Performance -```html - +Add `?v={hash}` cache-busting via `asset_url`: - +```liquid + ``` -### Color Contrast -Ensure sufficient contrast: +`asset_url` already appends a content-hash query parameter. Don't add +your own. -```scss -.pos-btn-primary { - background-color: #0062cc; // WCAG AAA compliant - color: #ffffff; -} +## Accessibility + +The shipped components ship with sane semantic markup (` ``` +For alerts, prefer the partial — it sets `role="alert"` and the icon for +you. + ## See Also -- configuration.md - Basic setup -- api.md - Component reference -- patterns.md - Common patterns -- gotchas.md - Common mistakes + +- [README](README.md) +- [API](api.md) +- [Configuration](configuration.md) +- [Patterns](patterns.md) +- [Gotchas](gotchas.md) +- [Prerequisites](prerequisites.md) diff --git a/src/data/references/modules/common-styling/api.md b/src/data/references/modules/common-styling/api.md index 69c41cf..ddfe6ca 100644 --- a/src/data/references/modules/common-styling/api.md +++ b/src/data/references/modules/common-styling/api.md @@ -1,122 +1,189 @@ -# modules/common-styling - API Reference +# modules/common-styling — API Reference -## Component Classes +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). The +> live class set is the source of truth — verify with +> `module_info(name: 'common-styling')` or scan `r.css_classes`. +> Fictional class names produce unstyled output. + +## Composition Philosophy + +This is a PARTIAL-FIRST framework, not a class-utility framework. For +anything more complex than a button or a heading, render a shipped +partial — they encode the design-system semantics correctly and ship the +right HTML structure. Hand-composing class soup is a footgun. + +## Buttons -### Buttons ```html - - - - - - + + + ``` -### Cards -```html -
    -
    -

    Card Header

    -
    -
    - Card content goes here -
    -
    - Footer text -
    -
    +`pos-button-{secondary,danger,success,large}` do NOT ship. + +## Cards + +Use the partial: + +```liquid +{% render 'modules/common-styling/content/card', + url: '/posts/1', title: 'Title', + content: 'Description', highlighted: true %} ``` -### Forms +If you need to compose by hand, the canonical structure is: + ```html -
    -
    - - -
    -
    - + ``` -### Alerts -```html -
    - Info: This is informational -
    +`pos-card-header` and `pos-card-body` do NOT ship — those are legacy +names. Use `pos-card-content` and `pos-card-content-footer`. -
    - Success: Operation completed -
    +## Alerts (use the partial) -
    - Warning: Check this -
    - -
    - Error: Something went wrong -
    +```liquid +{% render 'modules/common-styling/content/alert', + type: 'success', content: 'Saved.' %} ``` -### Pagination -```html - -``` +Renders `pos-card-alert pos-card-alert-success pos-card`. There is NO +`pos-alert-*` family — those names will NOT match any shipped CSS. +`type` must be one of: `success`, `error`, `warning`, `info`. + +## Toasts (notifications) -### File Upload ```html -
    - -
    - Drop files here or click to upload +
    +
    + Saved. +
    ``` -### Toasts -```html -
    - Successfully saved! - -
    +Toast variants: `pos-toast-success`, `pos-toast-error`, +`pos-toast-info`, `pos-toast-loading`, `pos-toast-unloading`. + +## Forms + +The shipped form partials handle the multi-element widgets: + +```liquid +{% render 'modules/common-styling/forms/error_list', + errors: errors.title, name: 'title' %} + +{% render 'modules/common-styling/forms/multiselect', + id: 'tags', name: 'tags', + options: tag_options, selected: object.tags %} + +{% render 'modules/common-styling/forms/password', + id: 'password', name: 'password' %} + +{% render 'modules/common-styling/forms/upload', + id: 'image', name: 'image', + presigned_upload: presigned, allowed_file_types: ['image/*'] %} + +{% render 'modules/common-styling/forms/hcaptcha' %} +{% render 'modules/common-styling/forms/markdown', id: 'body', name: 'body' %} ``` -## Utility Classes +Class families used inside these widgets: + +- Inputs: `pos-form-input`, `pos-form-checkbox`, `pos-form-fieldset`, + `pos-form-fieldset-combined`, `pos-form-actions`. +- Errors: `pos-form-error` on each `
  • ` inside an + `id="pos-form-{name}-error"` `
      ` (see `forms/error_list.liquid`). +- Multiselect: `pos-form-multiselect-*` family (filter, list, items). +- Password: `pos-form-password-*` family with strength indicators + (`pos-form-password-strength-{weak,medium,strong,1..3}`). + +`pos-input`, `pos-label`, `pos-form-group`, `pos-checkbox` (without the +`pos-form-` prefix) do NOT ship — those are legacy names. + +## Avatars -### Spacing ```html -
      Padding 1
      -
      Margin 2
      -
      Horizontal padding
      -
      Vertical margin
      +… ``` -### Text +Sizes: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl` — each as a modifier +class (`pos-avatar-md` etc.). + +## Tags / Chips + ```html -

      Primary text

      -

      Secondary text

      -

      Centered

      -

      Bold

      +
        +
      • confirmed
        • +
      • warn
        • +
      • !
        • +
      • click me
        • +
      +``` + +## Dialogs (modals) + +Use the partial: + +```liquid +{% render 'modules/common-styling/content/dialog', + id: 'confirm-delete', title: 'Delete?', + actions: actions_html, body: body_html %} ``` -### Display +Class structure: `pos-dialog`, `pos-dialog-header`, +`pos-dialog-actions`, `pos-dialog-close`. + +## Headings + ```html -
      Flexbox
      -
      Grid
      -
      Hidden
      +

      Title

      +

      + Section extra detail +

      +``` + +`pos-heading-1` … `pos-heading-6` ship. + +## Pagination + +```liquid +{% render 'modules/common-styling/navigation/pagination', + total_pages: result.records.total_pages %} ``` +The partial owns the class structure; `pos-pagination` is the wrapper. +`pos-page-link` does NOT ship as a standalone — render the partial. + +## Utility Classes (semantic, NOT atomic) + +The module ships a small semantic-utility set, NOT a Tailwind-style +atomic-utility set: + +- Gaps: `pos-gap-section-section`, `pos-gap-text-text`, + `pos-gap-button-button`, etc. (named by SEMANTIC pair, not size). +- Margins: `pos-mt-section-section`, `pos-mt-text-text`, etc. (top-only, + named pair). + +There is NO `pos-p-1`, `pos-m-2`, `pos-text-primary`, `pos-flex`, +`pos-grid`, `pos-col-*`, `pos-row`. If you need a grid layout, use +native CSS Grid / Flexbox via your own scoped class. + ## See Also -- configuration.md - Setup and initialization -- patterns.md - Common usage patterns -- gotchas.md - Common mistakes -- advanced.md - Advanced customization + +- [README](README.md) — overview + class inventory +- [Configuration](configuration.md) — setup + scope +- [Patterns](patterns.md) — common compositions +- [Gotchas](gotchas.md) — fictional-class footguns +- [Advanced](advanced.md) — overrides, dark-mode, custom themes +- [Prerequisites](prerequisites.md) — required app-side setup diff --git a/src/data/references/modules/common-styling/configuration.md b/src/data/references/modules/common-styling/configuration.md index 4b02aa9..74d9199 100644 --- a/src/data/references/modules/common-styling/configuration.md +++ b/src/data/references/modules/common-styling/configuration.md @@ -1,123 +1,167 @@ -# modules/common-styling - Configuration +# modules/common-styling — Configuration + +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). ## Overview -The `modules/common-styling` is a required module providing a comprehensive CSS framework with platformOS-specific styling. It includes pre-built components and utility classes. -## Installation and Initialization +`modules/common-styling` provides the CSS framework + reusable Liquid +partials for platformOS apps. It is partial-first: the shipped partials +are the canonical source of truth for component composition. The CSS is +scoped to a `.pos-app` container; design tokens live in +`pos-config.css` as CSS custom properties. -### Initialize in Application Layout -Add the init include to your main layout: +## Installation -```liquid -# app/layouts/application.html.liquid +```bash +pos-cli modules install common-styling +``` + +`common-styling` has no module dependencies (per `pos-module.json` 1.37.27). -{% render 'modules/common-styling/init' %} +## Required Initialization (canonical layout) +```liquid +{% comment %} app/views/layouts/application.html.liquid {% endcomment %} - - - {{ page.title }} - - - {{ content_for_layout }} - + + + {% render 'modules/common-styling/init' %} + + {{ page.title | default: 'My App' }} + + + {{ content_for_layout }} + ``` -### Required Wrapper Class -Always wrap your content with `pos-app`: +Two things MUST be present: -```html - - - -``` +1. `class="pos-app"` on the `` element (or a top-level scope + container if you're embedding in a host page that already has its own + styling). +2. `{% render 'modules/common-styling/init' %}` inside ``. This + injects the asset link tags. Without this render, the CSS never loads. -## Core CSS Framework +`init` may also be rendered inside `` if you can't touch ``, +but `` is canonical. -### Class Naming Convention -All framework classes use `pos-` prefix: +### Dark Mode ```html -
      -
      -

      Card Title

      -
      -
      - Content here -
      -
      + + + + + ``` -### Not Bootstrap or Tailwind -This is a custom framework designed specifically for platformOS: +## Asset Layout -```liquid - -
      -
      +CSS files ship under `modules/common-styling/public/assets/style/`: - -
      - + + + ``` -The style guide demonstrates: -- All available components -- Color palette -- Typography -- Spacing system -- Responsive behavior +## Style Guide -## Custom Styling Integration +Browse `/style-guide` on any instance for an interactive reference. Each +section corresponds to a partial under `views/partials/style-guide/` +(buttons, forms, toasts, headings, tables, etc.). -### Extending Styles -Add custom CSS alongside framework: +## Extending Styles via Custom CSS -```scss -// app/assets/styles/custom.scss -@import 'modules/common-styling/init'; +Use the shipped CSS variables for colors, gaps, typography. Don't +hard-code colors: -// Your custom styles here -.my-custom-class { - color: var(--pos-primary-color); +```css +/* app/assets/custom.css */ +.my-section { + color: var(--pos-color-light-content-text); + background: var(--pos-color-light-content-background); + border: 1px solid var(--pos-color-light-frame); + gap: var(--pos-gap-section-section); } ``` -### CSS Variables -Use platformOS CSS variables: +The token names follow `--pos-color-{light|dark}-{role}` and +`--pos-gap-{from-to}` conventions; inspect `pos-config.css` for the full +set. -```css -.custom-element { - color: var(--pos-text-primary); - background: var(--pos-background); - border: 1px solid var(--pos-border-color); -} +Add the asset to your layout via `asset_url`: + +```liquid + +``` + +## Component Library (renderable partials) + +Pre-built compositions: + +- `content/card`, `content/alert`, `content/dialog` +- `forms/error_list`, `forms/multiselect`, `forms/password`, + `forms/upload`, `forms/markdown`, `forms/hcaptcha` +- `navigation/collapsible`, `navigation/pagination` +- `user/avatar`, `user/card` +- `style-guide/*` (each section of the live style guide) + +```liquid +{% render 'modules/common-styling/content/card', ... %} ``` ## See Also -- api.md - Component API reference -- patterns.md - Common usage patterns -- gotchas.md - Common mistakes -- advanced.md - Advanced customization + +- [README](README.md) — class inventory +- [API](api.md) — class families + partial signatures +- [Patterns](patterns.md) — composition recipes +- [Gotchas](gotchas.md) — fictional-class footguns +- [Advanced](advanced.md) — overrides, custom themes +- [Prerequisites](prerequisites.md) — setup checklist diff --git a/src/data/references/modules/common-styling/gotchas.md b/src/data/references/modules/common-styling/gotchas.md index bc0e0a8..505056d 100644 --- a/src/data/references/modules/common-styling/gotchas.md +++ b/src/data/references/modules/common-styling/gotchas.md @@ -1,162 +1,182 @@ -# modules/common-styling - Common Gotchas +# modules/common-styling — Common Gotchas -## Critical: Do NOT Use Tailwind or Bootstrap +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). -Never import or use Bootstrap or Tailwind classes: +## TOP GOTCHA: Don't Hand-Compose Fictional Class Names -```html - -
      - -
      +A whole family of plausible-looking class names DO NOT ship in this +module. Putting them in your HTML produces unstyled output: - -
      - -
      -``` +| Fictional (don't use) | Reason | +|------------------------------------------------|-------------------------------------------------------| +| `pos-btn`, `pos-btn-primary` | Class is `pos-button`, not `pos-btn` | +| `pos-button-secondary` / `-danger` / `-success`/ `-large` | Only `pos-button-primary` and `pos-button-small` ship | +| `pos-card-header` / `pos-card-body` / `pos-card__title` | Use `pos-card-content`, `pos-card-content-title`, `pos-card-content-footer` | +| `pos-alert-success` / `pos-alert-error` / `pos-alert-warning` / `pos-alert-danger` | Use the `content/alert` partial OR `pos-card-alert pos-card-alert-{type}` | +| `pos-row`, `pos-col-12`, `pos-col-md-6` | NO grid system ships — use native CSS Grid/Flexbox | +| `pos-p-1`, `pos-m-2`, `pos-text-primary`, `pos-flex`, `pos-grid` | NO Tailwind-style atomic utilities ship | +| `pos-input`, `pos-label`, `pos-checkbox`, `pos-form-group` | Use `pos-form-input`, `pos-form-checkbox`, `pos-form-fieldset` | +| `pos-page-link active` (pagination) | Use the `navigation/pagination` partial | +| `pos-btn-block` | NO block helper ships — set `width: 100%` if you need it | + +ALWAYS verify a class name against the live scan +(`module_info(name: 'common-styling')` or +`r.css_classes.filter(c => c.startsWith('pos-'))`) before committing it. -Mixing frameworks causes CSS conflicts and breaks the design system. +## Don't Mix Tailwind / Bootstrap -## Missing pos-app Class +The shipped `pos-config.css` defines design tokens (CSS custom properties) +that the rest of the module consumes. Mixing Tailwind utilities or +Bootstrap classes leads to: -Always wrap your entire application with `pos-app`: +- Conflicting reset rules (Bootstrap's `*` reset fights `pos-reset.css`). +- Tokens out of sync — Tailwind's defaults override `--pos-color-*` vars, + breaking dark mode and theme overrides. ```html - - -
      - -
      - + + - - -
      - -
      - + + ``` -Without `pos-app`, many styles won't apply correctly. - -## Forgetting to Initialize +## `pos-app` Goes on ``, Not a Wrapper Div -Always include the init render in your main layout: +The shipped CSS scopes selectors to `.pos-app`. Without that class on a +container, NOTHING styles. Per the shipped style guide +(`partials/style-guide/initialization.liquid`), the canonical home is the +root `` tag: -```liquid - - - - - {{ content_for_layout }} - +```html + + + + {% render 'modules/common-styling/init' %} + + ... +``` - -{% render 'modules/common-styling/init' %} - - - - {{ content_for_layout }} +If you need to scope styles to a sub-tree (e.g. embedding in a host page +that already has its own framework), you can also put `pos-app` on a +container `
      ` — the styles cascade only inside it. + +```html + + + - ``` -## Class Name Typos +## Forgetting to Render `init` -Common typos cause styles to not apply: +`{% render 'modules/common-styling/init' %}` injects the asset link +tags. Without it, the CSS never loads: -```html - - -
      Wrong
      -Wrong +```liquid + + + App + ... + - -
      Right
      - + + + {% render 'modules/common-styling/init' %} + App + + ... + ``` -## Nested Card Structure +## Card Sub-Element Names (modernized) -Don't nest cards without proper structure: +The card sub-elements are hyphenated, not BEM: ```html - +
      -
      - -
      +
      Title
      +
      Body
      - -
      -
      -
      - Nested card content -
      -
      -
      + +
      +

      Title

      +

      Body

      +
      …
      +
      +``` + +For most cases, RENDER the partial instead of hand-composing: + +```liquid +{% render 'modules/common-styling/content/card', + url: '/x', title: 'Title', content: 'Body' %} ``` -## Form Group Mistakes +## Form Composition (modernized) -Don't skip form-group wrapper: +Forms use `pos-form-fieldset` (not `pos-form-group`) to wrap a label + +input. Inputs are `pos-form-input` (not `pos-input`): ```html - -
      - - -
      - - +
      - +
      + + +
      +
      + + +
      +
      ``` -## Inline vs Block Buttons +For complex widgets (multiselect, password, upload, hcaptcha, markdown), +RENDER the shipped partial under `forms/`: -Understand button sizing: +```liquid +{% render 'modules/common-styling/forms/upload', + id: 'image', name: 'image', + presigned_upload: presigned, allowed_file_types: ['image/*'] %} +``` -```html - - - +## Toasts vs Alerts — Different Things - -
      - -
      -``` +- **Alerts** are inline, content-flow notifications. + Use `content/alert` partial → renders as `pos-card-alert`. +- **Toasts** are floating, transient notifications. + Hand-composed using the `pos-toasts` container + `pos-toast` items. -## Alert Auto-Dismissal +There is NO `pos-alert-*` family. Don't confuse the two — alerts and +toasts have different visual + behavior contracts. -Alerts don't auto-dismiss: +## Pagination Active State -```html - -
      - Message persists forever -
      +The shipped pagination partial owns the active-page class. Don't hand-roll: - -
      - Success! - -
      +```liquid + +2 + + +{% render 'modules/common-styling/navigation/pagination', + total_pages: result.records.total_pages %} ``` ## See Also -- configuration.md - Setup instructions -- api.md - Component reference -- patterns.md - Common patterns -- advanced.md - Advanced customization + +- [README](README.md) — class inventory +- [API](api.md) — class families + partials +- [Configuration](configuration.md) — setup +- [Patterns](patterns.md) — composition recipes +- [Advanced](advanced.md) — overrides + custom themes +- [Prerequisites](prerequisites.md) — required setup checklist diff --git a/src/data/references/modules/common-styling/patterns.md b/src/data/references/modules/common-styling/patterns.md index 15ed92d..b3726a6 100644 --- a/src/data/references/modules/common-styling/patterns.md +++ b/src/data/references/modules/common-styling/patterns.md @@ -1,135 +1,163 @@ -# modules/common-styling - Common Patterns +# modules/common-styling — Common Patterns + +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). +> The framework is partial-first — render the shipped partials rather +> than hand-composing class soup. ## Layout Patterns ### Basic Page Layout -```liquid -{% render 'modules/common-styling/init' %} -
      -
      -
      -

      My App

      +```liquid +{% comment %} app/views/layouts/application.html.liquid {% endcomment %} + + + + {% render 'modules/common-styling/init' %} + {{ page.title | default: 'My App' }} + + +
      +

      My App

      -
      +
      {{ content_for_layout }}
      -
      -

      © 2024

      +
      +

      © 2026

      -
      -
      + + ``` -### Two-Column Layout +`pos-app` goes on the `` tag, NOT a wrapper `
      ` (per the +shipped style-guide). + +### Multi-Column Layout (use native CSS Grid/Flexbox) + +The module ships NO grid system. Use native CSS: + ```html -
      -
      -
      -
      Main content
      -
      -
      -
      Sidebar
      -
      -
      +
      + {% render 'modules/common-styling/content/card', title: 'Main', content: '...' %} + {% render 'modules/common-styling/content/card', title: 'Side', content: '...' %}
      ``` +Or scope a project-specific class in your own CSS file. Don't reach for +`pos-row` / `pos-col-*` — those don't ship. + ## Form Patterns -### Login Form -```html +### Login Form (composed via shipped partials) + +```liquid
      -
      - - -
      -
      - - +
      + + + {% render 'modules/common-styling/forms/error_list', + errors: errors.email, name: 'email' %} +
      + + {% render 'modules/common-styling/forms/password', + id: 'password', name: 'password' %} + +
      +
      - ``` ### Search Form -```html -
      -
      - -
      - + +```liquid + +
      + + +
      ``` -## Data Display Patterns +## Data Display ### Card List -```html -
      - {% for item in items %} -
      -
      -

      {{ item.title }}

      -
      -
      -

      {{ item.description }}

      -
      -
      - - View More - -
      -
      - {% endfor %} -
      + +```liquid +{% for item in items %} + {% render 'modules/common-styling/content/card', + url: item.url, + title: item.title, + content: item.description, + image: item.image, + highlighted: item.featured %} +{% endfor %} ``` -### Notification Display -```html -{% if message %} -
      - {{ message }} -
      +### Notification Display (use the alert partial, not class soup) + +```liquid +{% if notice %} + {% render 'modules/common-styling/content/alert', + type: 'success', content: notice %} {% endif %} {% if error %} -
      - {{ error }} -
      + {% render 'modules/common-styling/content/alert', + type: 'error', content: error %} {% endif %} ``` -## Pagination Pattern +For non-blocking notifications (toasts), render the toast structure +directly: + ```html - +
      +
      + Saved. + +
      +
      ``` +## Pagination + +```liquid +{% render 'modules/common-styling/navigation/pagination', + total_pages: result.records.total_pages, + current_page: context.params.page %} +``` + +The shipped partial owns the markup. There is no `pos-page-link active` +hand-composable class — use the partial. + +## Style-Guide Reference (live, on-instance) + +The module renders its own style guide at `/style-guide` for any instance +that has it installed. Each section has a corresponding partial under +`views/partials/style-guide/` (e.g. `buttons.liquid`, `forms.liquid`, +`toasts.liquid`) — use those as the canonical reference for class +combinations. + +## Dark Mode + +```html + + + + + +``` + +Components that ship dark variants pick them up automatically; no +component-level toggling is needed. + ## See Also -- configuration.md - Setup instructions -- api.md - Component reference -- gotchas.md - Common mistakes -- advanced.md - Advanced customization + +- [README](README.md) — overview + class inventory +- [API](api.md) — class families + render-able partials +- [Configuration](configuration.md) — setup +- [Gotchas](gotchas.md) — fictional-class footguns +- [Advanced](advanced.md) — overrides, custom themes +- [Prerequisites](prerequisites.md) — required setup before using this module diff --git a/src/data/references/modules/common-styling/prerequisites.md b/src/data/references/modules/common-styling/prerequisites.md new file mode 100644 index 0000000..54fa361 --- /dev/null +++ b/src/data/references/modules/common-styling/prerequisites.md @@ -0,0 +1,114 @@ +# modules/common-styling — Required Setup + +> Compatible with pos-cli 6.0.7+ (modernized canonical class names). +> Read this BEFORE adding any `pos-*` classes or rendering any +> `modules/common-styling/...` partial. + +## Mental Model + +This is a **partial-first**, **token-themed** CSS framework — not a +class-utility framework. Two corollaries: + +- For anything beyond a button or a heading, **render a shipped partial** + (`content/card`, `forms/upload`, `navigation/pagination`, etc.). +- For colors, gaps, spacing, **read the design tokens** in + `pos-config.css` (CSS custom properties) — don't hardcode values. + +The framework is NOT Tailwind, NOT Bootstrap, NOT a utility-class +generator. There are no atomic utilities like `pos-p-1`, `pos-text-primary`, +`pos-flex`, `pos-grid` — those names will NOT match any shipped CSS. + +## Three Required Setup Steps + +### 1. Render `init` in your layout `` + +```liquid +{% comment %} app/views/layouts/application.html.liquid {% endcomment %} + + + + {% render 'modules/common-styling/init' %} + ... + + ... + +``` + +`init` injects the `` tags for every shipped CSS asset (button, +card, forms, toast, dialog, etc.) plus the JS for the interactive widgets +(multiselect, password strength meter, collapsible). Without it, no +styles or behaviors load. + +### 2. Set `class="pos-app"` on the root element + +```html + +``` + +The shipped CSS is scoped to `.pos-app`. WITHOUT this class on a +container, NOTHING styles, even with `init` rendered. + +You can scope to a sub-tree instead of the whole `` if you're +embedding in a host page that has its own framework — put `pos-app` on a +container `
      ` and the styles only apply inside it. + +### 3. (Optional) Pick a theme mode + +```html + + + + + +``` + +If you don't add a theme class, the light theme is the default. + +## Setup Checklist + +- [ ] `pos-cli modules install common-styling` has been run. +- [ ] Layout `` contains `{% render 'modules/common-styling/init' %}`. +- [ ] Root `` (or top scope container) has `class="pos-app"`. +- [ ] No Tailwind / Bootstrap / utility-class generators are mixed in. +- [ ] Any custom CSS is loaded AFTER `init` so token overrides apply. +- [ ] You are using shipped partials for components (`content/card`, + `forms/...`, `navigation/...`) rather than hand-composing. +- [ ] You are verifying class names against the live scan (or + `module_info(name: 'common-styling')`) before committing them. + +## Verifying a Class Name Exists + +Before committing any `pos-*` class to your code: + +```bash +node -e "import('./src/core/module-scanner.js').then(m => m.scanModule('.', 'common-styling').then(r => console.log(r.css_classes.filter(c => c.startsWith('pos-')).join('\n'))))" | grep -E '^pos-button' +``` + +If the class does NOT appear in the scan output, it does NOT ship. + +## Module Dependencies + +Per `modules/common-styling/pos-module.json` (1.37.27): no module +dependencies. It is a peer of `core` and `user` rather than depending on +either. + +## Common First-Time Mistakes + +1. Forgetting `pos-app` on the root → all styles invisible. +2. Forgetting `init` → CSS files never load. +3. Reaching for Tailwind / Bootstrap classes out of habit (`btn`, + `container`, `flex`) — they don't ship. +4. Hand-composing `pos-alert-*`, `pos-card-header`, `pos-page-link + active`, `pos-form-group`, `pos-input` — these are LEGACY names that + no longer exist. Use the modern equivalents (see api.md and gotchas.md). +5. Loading custom CSS BEFORE `init` — your token overrides get reset + by `pos-config.css`. + +## See Also + +- [README](README.md) +- [API](api.md) +- [Configuration](configuration.md) +- [Patterns](patterns.md) +- [Gotchas](gotchas.md) +- [Advanced](advanced.md) diff --git a/src/data/references/modules/core/README.md b/src/data/references/modules/core/README.md index 955fb2d..fe975f5 100644 --- a/src/data/references/modules/core/README.md +++ b/src/data/references/modules/core/README.md @@ -1,80 +1,111 @@ # pos-module-core -The core module provides the **command pattern** infrastructure, **event system**, **validators**, **session helpers**, **flash messages**, and **redirect utilities** for every platformOS application. +The core module provides the canonical **build → check → execute** command +pattern, the **event system**, a comprehensive **validator** family, **session +helpers**, **flash messages**, and **redirect utilities** for every +platformOS application. -**Required module** -- must be installed in every project. All other modules depend on it. +**Required module** — every other module depends on it. +Compatible with pos-cli 6.0.7+ (modernized canonical syntax). ## Key Purpose -pos-module-core establishes the foundational architecture patterns for platformOS apps: - -1. **Command pattern** -- a three-step workflow (`build` -> `check` -> `execute`) for all data mutations -2. **Event system** -- publish/subscribe mechanism for decoupled side effects -3. **Validation** -- seven built-in validators (presence, numericality, uniqueness, length, format, inclusion, confirmation) -4. **Session management** -- get and clear session data for flash messages and temporary state -5. **Redirect helpers** -- redirect with flash messages in a single call - -Every create, update, and delete operation in a platformOS app should flow through the core command pattern. +pos-module-core ships the foundational primitives a platformOS app composes: + +1. **Command pattern** — `build → check → execute` is APP-LEVEL: each app + command defines its own `build` and `check` partials and finishes by + calling the shared `modules/core/commands/execute` to run the + underlying GraphQL mutation. The core module does NOT ship top-level + `commands/build` or `commands/check` files. +2. **Event system** — publish/subscribe via + `modules/core/commands/events/...` for decoupled side effects. +3. **Validators** — 19 validators under `modules/core/lib/validations/`: + presence, length, number, date, email, is_url, matches, equal, + uniqueness, included, elements_included, unique_elements, + each_element_length, password_complexity, hcaptcha, truthy, not_null, + exist_in_db, valid_object. +4. **Helpers** — `helpers/redirect_to`, `helpers/flash`, timezone utilities. +5. **Generators** — `pos-cli generators run command|crud` produces + build/check/execute scaffolds (templates ship under + `modules/core/generators/`). ## When to Use -- **Creating or updating records** -- use `build`, `check`, `execute` commands in your command partials -- **Validating user input** -- attach validators to fields before persisting -- **Publishing events** -- trigger side effects (emails, notifications, logging) after mutations -- **Flash messages** -- set a message in session before redirect, display on next page load -- **Redirecting with notice** -- use `redirect_to` helper to combine redirect and flash in one call +- **Creating / updating records** — write your build + check partials, then + call `modules/core/commands/execute` for the mutation. +- **Validating user input** — call core validators from `check`, attaching + errors to a contract object via `modules/core/helpers/register_error`. +- **Publishing events** — `modules/core/commands/events/publish` fires + side-effect chains. +- **Flash messages** — `modules/core/helpers/flash` stashes one-shot + messages; `helpers/redirect_to` combines redirect + flash. -You do NOT call core commands directly from pages. Instead, your `lib/commands/` partials call them internally. +You DO NOT call `commands/build` or `commands/check` from a page. Build/check +live INSIDE your own app commands; pages call your app command via +`{% function %}`. ## How It Works ``` -Page -> lib/commands/products/create -> core/commands/build - -> core/commands/check (with validators) - -> core/commands/execute (runs mutation) - -> core/commands/events/publish (optional) +Page → app/lib/commands/products/create + → app/lib/commands/products/create/build (your build) + → app/lib/commands/products/create/check (your check w/ validators) + → modules/core/commands/execute (mutation runner) + → modules/core/commands/events/publish (optional) ``` -1. A page collects `context.params` and calls a command partial via `{% function %}` -2. The command partial calls `build` to construct the object hash -3. The command partial calls `check` with a validators array to validate -4. If valid, the command partial calls `execute` to run the GraphQL mutation -5. Optionally, an event is published for side effects +1. The page collects `context.params` and calls your app command via + `{% function %}`. +2. Your app command's `build` partial assembles the object hash. +3. Your app command's `check` partial runs validators against the contract, + returning `object.valid` + `object.errors`. +4. If valid, your app command calls `modules/core/commands/execute` to run + the GraphQL mutation. +5. Optionally publish an event afterwards. -### Minimal command example +### Minimal app command (canonical) ```liquid {% comment %} app/lib/commands/products/create.liquid {% endcomment %} -{% function object = 'modules/core/commands/build', object: params %} -{% assign validators = [{ "name": "presence", "property": "title" }] %} -{% function object = 'modules/core/commands/check', object: object, validators: validators %} -{% if object.errors != blank %} +{% function object = 'commands/products/create/build', object: params %} +{% function object = 'commands/products/create/check', object: object %} +{% if object.valid == false %} {% return object %} {% endif %} {% function object = 'modules/core/commands/execute', - mutation_name: 'products/create', selection: 'record_create', object: object -%} + mutation_name: 'products/create', + selection: 'record_create', + object: object %} +{% return object %} +``` + +```liquid +{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %} +{% function c = 'modules/core/lib/validations/presence', + c: object.errors, field_name: 'title', object: object %} +{% function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 %} +{% assign object.errors = c %} +{% assign object.valid = c == empty %} {% return object %} ``` ## Getting Started -1. Install the module: - ```bash - pos-cli modules install core - ``` -2. Create a command partial in `app/lib/commands//create.liquid` -3. Use `build`, `check`, `execute` inside the command -4. Call the command from your page via `{% function result = 'lib/commands/products/create', params: context.params %}` -5. Handle `result.errors` in the page if validation fails +1. Install: `pos-cli modules install core` +2. Generate scaffolds: + `pos-cli generators run crud --resource products` +3. Customize the generated `build` / `check` partials. +4. Call the command from your page: + `{% function result = 'commands/products/create', object: context.params %}` +5. Handle `result.errors` in the page. ## See Also -- [Core Configuration](configuration.md) -- installation and setup details -- [Core API](api.md) -- all commands, events, session, and validator functions -- [Core Patterns](patterns.md) -- real-world command and event workflows -- [Core Gotchas](gotchas.md) -- common errors and limits -- [Core Advanced](advanced.md) -- custom validators, event chaining, overrides -- [User Module](../user/README.md) -- authentication and RBAC (depends on core) -- [Commands Reference](../../commands/README.md) -- the command pattern in detail -- GitHub: https://github.com/Platform-OS/pos-module-core +- [Core Configuration](configuration.md) — installation and module layout +- [Core API](api.md) — validator family, helpers, command runner shape +- [Core Patterns](patterns.md) — real-world build/check/execute workflows +- [Core Gotchas](gotchas.md) — common errors (esp. "core/commands/build doesn't exist") +- [Core Advanced](advanced.md) — custom validators, event chaining +- Live API surface: `module_info(name: 'core', section: 'api')` +- Upstream: https://github.com/Platform-OS/pos-module-core diff --git a/src/data/references/modules/core/advanced.md b/src/data/references/modules/core/advanced.md index e81d7dc..4808793 100644 --- a/src/data/references/modules/core/advanced.md +++ b/src/data/references/modules/core/advanced.md @@ -1,177 +1,189 @@ -# pos-module-core -- Advanced Topics +# pos-module-core — Advanced Topics -Advanced customization, edge cases, and optimization techniques for the core module. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). ## Custom Validators -You can create custom validators by adding files to your app that follow the core validator interface. +Validators are plain Liquid partials that take a contract `c`, a +`field_name`, and the `object` plus any validator-specific options. +They APPEND to the contract via `modules/core/helpers/register_error` +and return the updated contract. ### Creating a custom validator -1. Create the validator file: - ```liquid -{% comment %} app/lib/validators/phone_number.liquid {% endcomment %} +{% comment %} app/lib/validations/phone_number.liquid {% endcomment %} +{% doc %} + @param {object} c - error contract + @param {string} field_name - field to validate + @param {object} object - object under validation + @param {string} message - optional override for the error message +{% enddoc %} {% liquid - assign value = object[property] + assign value = object[field_name] assign phone_regex = '^\+?[0-9]{10,15}$' - assign is_valid = value | matches: phone_regex - - if is_valid != true - assign errors[property] = 'is not a valid phone number' + if value != blank + assign ok = value | matches: phone_regex + if ok != true + assign message = message | default: 'errors.phone_invalid' | t + function c = 'modules/core/helpers/register_error', + contract: c, field_name: field_name, message: message, key: null + endif endif - - return errors + return c %} ``` -2. Reference it in your validators array with a custom path: +### Calling it from your check partial ```liquid -{% assign validators = [{ "name": "presence", "property": "phone" }, { "name": "phone_number", "property": "phone" }] %} +{% function c = 'lib/validations/phone_number', + c: c, field_name: 'phone', object: object %} ``` -**Note:** Custom validators must follow the same interface: accept `object` and `property`, return an `errors` hash. +The same calling convention works whether the validator is shipped +(`modules/core/lib/validations/...`), an override +(`app/modules/core/public/lib/validations/...`), or a fully custom +app-level one (`app/lib/validations/...`). ## Overriding Built-in Validators -To change how a built-in validator works (e.g., custom error messages): +To customize a shipped validator (e.g. tighter error messages): ```bash -mkdir -p app/modules/core/public/lib/validators -cp modules/core/public/lib/validators/presence.liquid \ - app/modules/core/public/lib/validators/presence.liquid +mkdir -p app/modules/core/public/lib/validations +cp modules/core/public/lib/validations/presence.liquid \ + app/modules/core/public/lib/validations/presence.liquid ``` -Edit the copy in `app/modules/core/` to customize behavior. The app-level file takes precedence. +Edit the copy. The override at `app/modules/core/public/...` wins over +the shipped file. ## Event Chaining -Events can trigger commands that publish more events, creating a chain: +Events can trigger commands that publish more events: ``` -order_created -> send_confirmation_email - -> update_inventory -> inventory_low -> notify_admin - -> update_analytics +order_created → send_confirmation_email + → update_inventory → inventory_low → notify_admin + → update_analytics ``` -### Implementing event chains - ```liquid -{% comment %} app/lib/consumers/order_created/update_inventory.liquid {% endcomment %} +{% comment %} app/lib/events/order_created/update_inventory.liquid {% endcomment %} {% liquid - function result = 'lib/commands/inventory/decrement', order: object + function result = 'commands/inventory/decrement', object: object if result.quantity < result.reorder_threshold function _ = 'modules/core/commands/events/publish', - type: 'inventory_low', - object: result + type: 'inventory_low', object: result endif return result %} ``` -**Warning:** Avoid circular event chains. If event A triggers event B which triggers event A, you create an infinite loop. +Avoid circular chains — if A triggers B which triggers A, you have an +infinite loop. The platform doesn't break it for you. ## Conditional Validation -Apply validators only when certain conditions are met: - ```liquid -{% comment %} app/lib/commands/products/create.liquid {% endcomment %} +{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %} {% liquid - function object = 'modules/core/commands/build', object: params + assign c = object.errors | default: empty - assign validators = [{ "name": "presence", "property": "title" }, { "name": "presence", "property": "status" }] + function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'title', object: object + function c = 'modules/core/lib/validations/included', + c: c, field_name: 'status', object: object, + in: ['draft','published','archived'] if object.status == 'published' - assign publish_validators = [{ "name": "presence", "property": "description" }, { "name": "presence", "property": "price" }, { "name": "numericality", "property": "price", "options": { "greater_than": 0 } }] - assign validators = validators | concat: publish_validators - endif - - function object = 'modules/core/commands/check', object: object, validators: validators - - if object.errors != blank - return object + function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'description', object: object + function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 endif - function object = 'modules/core/commands/execute', - mutation_name: 'products/create', selection: 'record_create', object: object + assign object.errors = c + assign object.valid = c == empty return object %} ``` -## Multi-Step Commands +## Multi-Step / Nested Commands -For complex operations that span multiple tables: +For operations that span tables, run each sub-command in sequence and +short-circuit on the first failure: ```liquid {% comment %} app/lib/commands/orders/create.liquid {% endcomment %} {% liquid - comment Create the order record first - endcomment - function order = 'modules/core/commands/build', object: order_params - function order = 'modules/core/commands/check', object: order, validators: order_validators - if order.errors != blank + function order = 'commands/orders/create/build', object: order_params + function order = 'commands/orders/create/check', object: order + if order.valid == false return order endif function order = 'modules/core/commands/execute', - mutation_name: 'orders/create', selection: 'record_create', object: order + mutation_name: 'orders/create', + selection: 'record_create', + object: order - comment Then create each line item - endcomment for item in line_items assign item['order_id'] = order.id - function line = 'modules/core/commands/build', object: item - function line = 'modules/core/commands/execute', - mutation_name: 'order_items/create', selection: 'record_create', object: line + function line = 'commands/order_items/create', object: item + if line.valid == false + log line.errors, type: 'orders/create line_item failed' + endif endfor - function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order + function _ = 'modules/core/commands/events/publish', + type: 'order_created', object: order + return order %} ``` -## Scoped Uniqueness Validation +For multi-step rollback semantics, wrap in `{% transaction %}` (platform +primitive) — outside the scope of `commands/execute`. -Validate uniqueness within a scope (e.g., slug unique per category): +## Scoped Uniqueness -```json -{ - "name": "uniqueness", - "property": "slug", - "options": { - "table": "product", - "scope": ["category_id"] - } -} +`uniqueness` accepts a `scope:` (array of field names) so the unique +constraint applies only WITHIN matching values: + +```liquid +{% function c = 'modules/core/lib/validations/uniqueness', + c: c, field_name: 'slug', object: object, + table: 'product', scope: ['category_id'] %} ``` -This checks that `slug` is unique only among records with the same `category_id`. +This rejects duplicate `slug` only among rows with the same +`category_id`. ## Batch Operations -For bulk creates or updates, loop through items and collect results: - ```liquid {% liquid assign results = '' | split: '' assign all_valid = true for item in items - function object = 'modules/core/commands/build', object: item - function object = 'modules/core/commands/check', object: object, validators: validators - if object.errors != blank + function obj = 'commands/products/create/build', object: item + function obj = 'commands/products/create/check', object: obj + if obj.valid == false assign all_valid = false endif - assign results = results | add_to_array: object + assign results = results | add_to_array: obj endfor if all_valid - for object in results - function object = 'modules/core/commands/execute', - mutation_name: 'products/create', selection: 'record_create', object: object + for obj in results + function obj = 'modules/core/commands/execute', + mutation_name: 'products/create', + selection: 'record_create', + object: obj endfor endif @@ -179,36 +191,36 @@ For bulk creates or updates, loop through items and collect results: %} ``` -## Performance Optimization +## Performance Notes -### Minimize validator calls +### Cheap before expensive -Each validator may run a database query (especially `uniqueness`). Group validators thoughtfully: +Validators may hit the DB (`uniqueness`, `exist_in_db`). Order them +cheapest-first so a missing required field never reaches the slow check: ```liquid -{% comment %} Run cheap validators first, expensive ones last {% endcomment %} -{% assign validators = [ - { "name": "presence", "property": "title" }, - { "name": "presence", "property": "email" }, - { "name": "format", "property": "email", "options": { "pattern": "^[^@]+@[^@]+$" } }, - { "name": "uniqueness", "property": "email", "options": { "table": "user_profile" } } -] %} +{% function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'email', object: object %} +{% function c = 'modules/core/lib/validations/email', + c: c, field_name: 'email', object: object %} +{% function c = 'modules/core/lib/validations/uniqueness', + c: c, field_name: 'email', object: object, table: 'user_profile' %} ``` ### Lean event payloads -Pass only IDs in event payloads; let consumers fetch what they need: +Pass only IDs; let consumers fetch what they need: ```liquid -{% assign payload = { "id": object.id, "type": "product" } %} -{% function _ = 'modules/core/commands/events/publish', type: 'product_created', object: payload %} +{% assign payload = { id: object.id, type: 'product' } %} +{% function _ = 'modules/core/commands/events/publish', + type: 'product_created', object: payload %} ``` ## See Also -- [Core Overview](README.md) -- introduction and key concepts -- [Core API](api.md) -- all available functions -- [Core Configuration](configuration.md) -- installation and validator options -- [Core Patterns](patterns.md) -- standard workflows -- [Core Gotchas](gotchas.md) -- common errors and limits -- [Events & Consumers](../../events-consumers/README.md) -- event consumer registration +- [Core Overview](README.md) +- [Core API](api.md) — full validator inventory + option names +- [Core Configuration](configuration.md) +- [Core Patterns](patterns.md) +- [Core Gotchas](gotchas.md) diff --git a/src/data/references/modules/core/api.md b/src/data/references/modules/core/api.md index 2c671a6..a972257 100644 --- a/src/data/references/modules/core/api.md +++ b/src/data/references/modules/core/api.md @@ -1,229 +1,160 @@ -# pos-module-core -- API Reference +# pos-module-core — API Reference -This document covers all available commands, helpers, validators, and event functions provided by the core module. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The live +> API surface is the source of truth — call +> `module_info(name: 'core', section: 'api')`. This file gives narrative +> notes on the validator family + the canonical command-runner shape. -## Commands +## Command Runner: `modules/core/commands/execute` -### modules/core/commands/build - -Constructs an object hash from input parameters. Strips unwanted keys and normalizes the data structure. +`execute` is the only top-level command-runner the module ships. There is +NO `modules/core/commands/build` or `modules/core/commands/check` — those +phases live INSIDE your app commands (or domain-specific module commands +like `commands/email/send/build`). Calling +`'modules/core/commands/build'` will fail with "partial not found" — see +gotchas.md. ```liquid -{% function object = 'modules/core/commands/build', object: params %} +{% function object = 'modules/core/commands/execute', + mutation_name: 'products/create', + selection: 'record_create', + object: object %} ``` -| Parameter | Type | Required | Description | -|-----------|------|----------|--------------------------------------| -| `object` | Hash | Yes | Raw input hash (typically from params)| - -**Returns:** A normalized hash ready for validation. +| Parameter | Type | Required | Description | +|-----------------|--------|----------|------------------------------------------------| +| `mutation_name` | String | Yes | GraphQL mutation path | +| `selection` | String | No | GraphQL result selection key (default `record`) | +| `object` | Hash | Yes | Validated object passed as `args` | -### modules/core/commands/check +**Returns:** the selected record from the mutation result, with +`object.valid = true` set on success. -Validates an object against an array of validators. Populates `object.errors` if validation fails. +## Domain Commands -```liquid -{% function object = 'modules/core/commands/check', object: object, validators: validators %} -``` +The core module ships several domain-specific commands that themselves use +the build/check pattern internally: -| Parameter | Type | Required | Description | -|--------------|-------|----------|-------------------------------------| -| `object` | Hash | Yes | Object to validate | -| `validators` | Array | Yes | JSON array of validator definitions | - -**Returns:** The object with an `errors` hash appended. If valid, `object.errors` is blank. - -```liquid -{% comment %} Check errors after validation {% endcomment %} -{% if object.errors != blank %} - {% comment %} object.errors looks like: { "title": ["can't be blank"], "price": ["is not a number"] } {% endcomment %} - {% return object %} -{% endif %} -``` +- `commands/email/send` — calls `email/send/build`, `email/send/check`, + then `graphql modules/core/email/send`. +- `commands/events/create` — calls `events/create/build`, + `events/create/check`, then `events/create/execute`. +- `commands/statuses/create` and `commands/statuses/delete` — same shape. -### modules/core/commands/execute - -Persists the object to the database by running a GraphQL mutation. - -```liquid -{% function object = 'modules/core/commands/execute', - mutation_name: 'products/create', - selection: 'record_create', - object: object -%} -``` - -| Parameter | Type | Required | Description | -|-----------------|--------|----------|----------------------------------------------| -| `mutation_name` | String | Yes | Path to GraphQL mutation file | -| `selection` | String | Yes | GraphQL selection field (e.g., `record_create`, `record_update`, `record_delete`) | -| `object` | Hash | Yes | Validated object to persist | - -**Returns:** The object with the database ID populated on success. +Use `module_info(name: 'core', section: 'api')` for the live param lists. ## Event Commands -### modules/core/commands/events/publish - -Publishes an event that can be consumed by event subscribers. - ```liquid {% function _ = 'modules/core/commands/events/publish', - type: 'product_created', - object: object -%} -``` + type: 'product_created', + object: object %} -| Parameter | Type | Required | Description | -|-----------|--------|----------|------------------------------------| -| `type` | String | Yes | Event type name | -| `object` | Hash | Yes | Data payload to pass to consumers | +{% function _ = 'modules/core/commands/events/broadcast', + type: 'inventory.changed', + object: object %} +``` -**Returns:** nil. Events are fire-and-forget from the publisher's perspective. +| Param | Type | Description | +|---------|--------|------------------------------------------| +| `type` | String | Event-type identifier | +| `object`| Hash | Payload passed to subscribers | ## Session Commands -### modules/core/commands/session/get - -Retrieves a value from the session store. - ```liquid {% function value = 'modules/core/commands/session/get', key: 'sflash' %} -``` - -| Parameter | Type | Required | Description | -|-----------|--------|----------|----------------------| -| `key` | String | Yes | Session key to read | - -**Returns:** The stored value, or nil if not set. -### modules/core/commands/session/set - -Stores a value in the session store. - -```liquid {% function _ = 'modules/core/commands/session/set', - key: 'sflash', value: 'Success message', from: context.location.pathname -%} -``` + key: 'sflash', value: 'Saved.', + from: context.location.pathname %} -| Parameter | Type | Required | Description | -|-----------|--------|----------|--------------------------------------------| -| `key` | String | Yes | Session key to write | -| `value` | Any | Yes | Value to store | -| `from` | String | No | Origin path for auto-clear (flash pattern) | - -### modules/core/commands/session/clear - -Removes a value from the session store. - -```liquid {% function _ = 'modules/core/commands/session/clear', key: 'sflash' %} ``` -| Parameter | Type | Required | Description | -|-----------|--------|----------|-----------------------| -| `key` | String | Yes | Session key to remove | +`from` is used by the flash auto-clear pattern: a flash set with `from` +is cleared on the next request that did NOT come from that origin path. ## Helpers -### modules/core/helpers/redirect_to - -Redirects to a URL with an optional flash notice. Combines session set and redirect in one call. +### `modules/core/helpers/redirect_to` ```liquid -{% include 'modules/core/helpers/redirect_to', url: '/products', notice: 'app.product_created' %} -``` - -| Parameter | Type | Required | Description | -|-----------|--------|----------|------------------------------------| -| `url` | String | Yes | Redirect target URL | -| `notice` | String | No | Translation key for flash message | - -### modules/core/helpers/flash/publish - -Sets a flash message without redirecting. +{% function _ = 'modules/core/helpers/redirect_to', + url: '/products', notice: 'app.product_created' %} +``` + +| Param | Type | Description | +|----------|--------|------------------------------------------| +| `url` | String | Redirect target | +| `notice` | String | Translation key for the flash notice | +| `error` | String | Translation key for an error flash | +| `info` | String | Translation key for an info flash | +| `default`| String | Translation key for a default flash | +| `format` | String | Optional format for the flash payload | + +### `modules/core/helpers/flash` + +Reads or composes flash messages. Used internally by `redirect_to` and by +your layout when rendering a flash banner. + +## Validators (canonical name + option shapes) + +All validators take `c` (contract / errors hash), `field_name`, `object`, +optional `message`, and validator-specific options. They APPEND to the +contract and RETURN it; chain them in your `check` partial. + +| Validator | Options (modern names) | Notes | +|--------------------------|---------------------------------------------------------|-------| +| `presence` | `allow_blank`, `message` | Falsey-blank fails | +| `length` | `min`, `max`, `eq` | String length | +| `number` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | Replaces legacy `numericality` with `greater_than`/`less_than` | +| `date` | `format`, `before`, `after` | | +| `email` | (none) | | +| `is_url` | (none) | | +| `matches` | `regexp`, `allow_blank` | Replaces legacy `format` (with param `pattern`) | +| `equal` | `to` | Replaces legacy `confirmation` — set `to: 'password_confirmation'` for the pwd-match case | +| `included` | `in` | Replaces legacy `inclusion.values` | +| `elements_included` | `in` | Same as `included` but on array fields | +| `unique_elements` | (none) | Array elements must be unique | +| `each_element_length` | `min`, `max` | | +| `uniqueness` | `table`, `scope` | | +| `password_complexity` | `min_length`, `require_digit`, `require_special`, ... | | +| `hcaptcha` | (none) | hCaptcha verification | +| `truthy` | (none) | Field must be truthy | +| `not_null` | (none) | Field must not be `nil` | +| `exist_in_db` | `table`, `field` | Foreign-key existence | +| `valid_object` | `validators` | Recursive sub-object validation | + +### Calling pattern ```liquid -{% include 'modules/core/helpers/flash/publish', notice: 'app.saved' %} -``` - -| Parameter | Type | Required | Description | -|-----------|--------|----------|-----------------------------------| -| `notice` | String | No | Translation key for notice flash | - -## Validators - -All validators are called internally by `modules/core/commands/check`. You configure them via the validators JSON array. - -### presence - -Field must not be blank, nil, or empty string. - -```json -{ "name": "presence", "property": "title" } -``` - -### numericality - -Field must be a valid number. - -```json -{ "name": "numericality", "property": "price" } -{ "name": "numericality", "property": "price", "options": { "greater_than": 0 } } -{ "name": "numericality", "property": "quantity", "options": { "less_than": 1000 } } -``` - -### uniqueness - -Field value must be unique within the specified table. - -```json -{ "name": "uniqueness", "property": "email", "options": { "table": "user_profile" } } -{ "name": "uniqueness", "property": "slug", "options": { "table": "product", "scope": ["category_id"] } } -``` - -### length - -String length must be within specified bounds. - -```json -{ "name": "length", "property": "title", "options": { "minimum": 1, "maximum": 255 } } -{ "name": "length", "property": "bio", "options": { "maximum": 1000 } } -``` - -### format - -Field must match a regular expression pattern. - -```json -{ "name": "format", "property": "email", "options": { "pattern": "^[^@]+@[^@]+\\.[^@]+$" } } -{ "name": "format", "property": "phone", "options": { "pattern": "^\\+?[0-9\\-\\s]+$" } } -``` - -### inclusion - -Field value must be one of the allowed values. - -```json -{ "name": "inclusion", "property": "status", "options": { "values": ["draft", "published", "archived"] } } -``` +{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %} +{% function c = 'modules/core/lib/validations/presence', + c: object.errors, field_name: 'title', object: object %} -### confirmation +{% function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 %} -Two fields must have matching values (e.g., password and password_confirmation). +{% function c = 'modules/core/lib/validations/matches', + c: c, field_name: 'sku', object: object, + regexp: '^[A-Z]{2,4}-[0-9]{4}$', allow_blank: true %} -```json -{ "name": "confirmation", "property": "password" } +{% assign object.errors = c %} +{% assign object.valid = c == empty %} +{% return object %} ``` -This checks that `password` equals `password_confirmation` in the object. +Legacy validator names that NO LONGER EXIST: `numericality` (use `number`), +`format` (use `matches`), `confirmation` (use `equal`), `inclusion` (use +`included`). Code that still references those will fail at function-resolve +time. ## See Also -- [Core Overview](README.md) -- introduction and key concepts -- [Core Configuration](configuration.md) -- installation and setup -- [Core Patterns](patterns.md) -- real-world usage examples -- [Core Gotchas](gotchas.md) -- common errors and limits -- [Core Advanced](advanced.md) -- custom validators and event chaining -- [Commands Reference](../../commands/README.md) -- the command pattern architecture +- [Core Overview](README.md) — introduction +- [Core Configuration](configuration.md) — installation + module layout +- [Core Patterns](patterns.md) — build/check/execute workflows +- [Core Gotchas](gotchas.md) — common errors (esp. phantom build/check) +- [Core Advanced](advanced.md) — custom validators, event chaining +- Live API: `module_info(name: 'core', section: 'api')` diff --git a/src/data/references/modules/core/configuration.md b/src/data/references/modules/core/configuration.md index 9131d2b..270ceec 100644 --- a/src/data/references/modules/core/configuration.md +++ b/src/data/references/modules/core/configuration.md @@ -1,6 +1,6 @@ -# pos-module-core -- Configuration Reference +# pos-module-core — Configuration -This document covers installation, setup, and configuration options for the core module. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). ## Installation @@ -8,141 +8,161 @@ This document covers installation, setup, and configuration options for the core pos-cli modules install core ``` -This creates the `modules/core/` directory in your project. This directory is **read-only** -- never edit files inside `modules/core/` directly. +This creates `modules/core/` in your project. The directory is **read-only** +— never edit files inside `modules/core/` directly. To customize, override +under `app/modules/core/public/...`. ### Verify installation -After installing and deploying, confirm the module is available: - -```liquid -{% function test = 'modules/core/commands/build', object: null %} -{% log test, type: 'debug' %} +```bash +ls modules/core/pos-module.json ``` -If you see output in logs without errors, the module is installed correctly. +The manifest reports `version`, `name`, and `dependencies: {}` (core has no +module deps). Re-run `pos-cli modules version core` if `template-values.json` +drifts from `pos-module.json`. -## Directory Structure +## Live Module Layout (2.1.8) ``` -modules/core/ # READ-ONLY -- installed module code +modules/core/ + pos-module.json + template-values.json # mirror of pos-module.json (sync via `pos-cli modules version`) + generators/ + command/templates/ # used by `pos-cli generators run command` + crud/templates/ # used by `pos-cli generators run crud` public/ lib/ commands/ - build.liquid # Construct object hash - check.liquid # Validate with validators array - execute.liquid # Run GraphQL mutation - events/ - publish.liquid # Publish an event - session/ - get.liquid # Get session value - set.liquid # Set session value - clear.liquid # Clear session value + execute.liquid # the only top-level command runner + session/{get,set,clear}.liquid + events/{create,broadcast,publish}.liquid + events/create/{build,check,execute}.liquid + email/send.liquid + email/send/{build,check}.liquid + statuses/{create,delete}.liquid + statuses/{create,delete}/{build,check}.liquid + variable/set.liquid + hook/{alter,fire}.liquid + queries/ + registry/, hook/, events/, statuses/, headscripts/, variable/, + constants/, module/ helpers/ - redirect_to.liquid # Redirect with flash - flash/ - publish.liquid # Set flash message - validators/ - presence.liquid - numericality.liquid - uniqueness.liquid - length.liquid - format.liquid - inclusion.liquid - confirmation.liquid + redirect_to.liquid + flash.liquid + timezone/... + register_error.liquid # appends an error to a contract + validations/ + presence, length, number, date, email, is_url, matches, equal, + uniqueness, included, elements_included, unique_elements, + each_element_length, password_complexity, hcaptcha, truthy, + not_null, exist_in_db, valid_object + events/ # subscriber stubs for the shipped event types + schema/ + status.yml + translations/ + en.yml + views/ # admin pages, layouts, partials ``` +There is NO `lib/commands/build.liquid` or `lib/commands/check.liquid` — +those phases are app-level (or domain-specific within other commands). + ## Overriding Module Files -The `modules/core/` directory is read-only. To customize behavior, copy the specific file to the `app/modules/core/` mirror path: +The override path mirrors the module tree under `app/modules/core/public/`: ```bash # Example: override the presence validator -mkdir -p app/modules/core/public/lib/validators -cp modules/core/public/lib/validators/presence.liquid \ - app/modules/core/public/lib/validators/presence.liquid +mkdir -p app/modules/core/public/lib/validations +cp modules/core/public/lib/validations/presence.liquid \ + app/modules/core/public/lib/validations/presence.liquid ``` -The file at `app/modules/core/public/...` takes precedence over the one in `modules/core/public/...`. +The file at `app/modules/core/public/...` takes precedence over the +shipped one. Override sparingly — keep diffs minimal so module updates +don't conflict. -**Rule:** Only override what you need. Keep overrides minimal to avoid breaking updates. +## Validator Calling Convention -## Validator Configuration +Validators are invoked individually with named parameters; chain them in +your check partial. There is NO config-driven JSON-array form. -Validators are configured as a JSON array passed to `check`. Each entry has: +```liquid +{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %} +{% liquid + assign c = object.errors | default: empty -| Property | Type | Required | Description | -|------------|--------|----------|--------------------------------------------| -| `name` | String | Yes | Validator name (e.g., `presence`) | -| `property` | String | Yes | Field name on the object to validate | -| `options` | Hash | No | Validator-specific options | + function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'title', object: object -### Validator options reference + function c = 'modules/core/lib/validations/length', + c: c, field_name: 'title', object: object, min: 3, max: 255 -| Validator | Option | Type | Description | -|----------------|----------------|---------|----------------------------------------| -| `length` | `minimum` | Integer | Minimum string length | -| `length` | `maximum` | Integer | Maximum string length | -| `numericality` | `greater_than` | Number | Value must be greater than this | -| `numericality` | `less_than` | Number | Value must be less than this | -| `format` | `pattern` | String | Regex pattern the value must match | -| `inclusion` | `values` | Array | Allowed values list | -| `uniqueness` | `table` | String | Table name to check uniqueness against | -| `uniqueness` | `scope` | Array | Additional fields for scoped uniqueness| -| `confirmation` | `field` | String | Name of the confirmation field | + function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 -### Example: full validator array + function c = 'modules/core/lib/validations/matches', + c: c, field_name: 'sku', object: object, + regexp: '^[A-Z]{2,4}-[0-9]{4}$', allow_blank: true -```liquid -{% assign validators = [ - { "name": "presence", "property": "title" }, - { "name": "presence", "property": "email" }, - { "name": "length", "property": "title", "options": { "minimum": 3, "maximum": 255 } }, - { "name": "numericality", "property": "price", "options": { "greater_than": 0 } }, - { "name": "format", "property": "email", "options": { "pattern": "^[^@]+@[^@]+\\.[^@]+$" } }, - { "name": "uniqueness", "property": "slug", "options": { "table": "product" } }, - { "name": "inclusion", "property": "status", "options": { "values": ["draft", "published", "archived"] } }, - { "name": "confirmation", "property": "password" } -] %} + function c = 'modules/core/lib/validations/uniqueness', + c: c, field_name: 'slug', object: object, table: 'product' + + function c = 'modules/core/lib/validations/equal', + c: c, field_name: 'password', object: object, to: 'password_confirmation' + + function c = 'modules/core/lib/validations/included', + c: c, field_name: 'status', object: object, in: ['draft','published','archived'] + + assign object.errors = c + assign object.valid = c == empty + return object +%} ``` -## Session Configuration +See api.md for the full validator inventory + each validator's option set. -Session helpers use platformOS built-in session storage. No additional configuration is needed. +## Session Storage -| Function | Key Parameter | Description | -|---------------|---------------|-----------------------------------| -| `session/get` | `key` | Retrieve a value from session | -| `session/set` | `key`, `value`| Store a value in session | -| `session/clear`| `key` | Remove a value from session | +Session helpers use the platformOS built-in session store; no extra config. -The `sflash` key is the conventional key used for flash messages (session-flash). +| Function | Description | +|-------------------|-----------------------------------| +| `session/get` | Retrieve a value | +| `session/set` | Store a value (`from:` for flash) | +| `session/clear` | Remove a value | -## Flash Message Configuration +The `sflash` key is the conventional flash-message slot. -The flash system uses `sflash` session key by convention. The `from` parameter on `session/set` ensures the flash auto-clears after display: +## Flash Message Configuration ```liquid {% function _ = 'modules/core/commands/session/set', - key: 'sflash', value: 'Record saved', from: context.location.pathname -%} + key: 'sflash', value: 'Record saved.', + from: context.location.pathname %} ``` +The `from` value lets the flash auto-clear when the next request comes +from a different origin. + ## Dependencies -pos-module-core has no module dependencies. It is the base module that all others depend on. +`pos-module-core` has no module dependencies. It is the base module the +rest of the ecosystem composes on: -| Module | Depends on core? | -|----------------------|------------------| -| pos-module-user | Yes | -| pos-module-payments | Yes | -| pos-module-tests | Yes | -| pos-module-chat | Yes | -| pos-module-openai | Yes | +| Module | Depends on core | +|------------------------|------------------| +| `pos-module-user` | Yes | +| `pos-module-common-styling` | No (peer) | +| `pos-module-payments` | Yes | +| `pos-module-tests` | Yes (dev only) | +| `pos-module-oauth_github` | Yes (via user) | ## See Also -- [Core Overview](README.md) -- introduction and key concepts -- [Core API](api.md) -- all available functions and helpers -- [Core Patterns](patterns.md) -- real-world usage patterns -- [Core Gotchas](gotchas.md) -- common errors and limits -- [Core Advanced](advanced.md) -- custom validators and overrides +- [Core Overview](README.md) +- [Core API](api.md) +- [Core Patterns](patterns.md) +- [Core Gotchas](gotchas.md) +- [Core Advanced](advanced.md) diff --git a/src/data/references/modules/core/gotchas.md b/src/data/references/modules/core/gotchas.md index 31c3ee7..e7d2fb3 100644 --- a/src/data/references/modules/core/gotchas.md +++ b/src/data/references/modules/core/gotchas.md @@ -1,72 +1,148 @@ -# pos-module-core -- Gotchas & Troubleshooting +# pos-module-core — Gotchas & Troubleshooting -Common errors, limits, and debugging guidance for the core module. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). -## Common Errors +## TOP GOTCHA: `modules/core/commands/build` and `…/check` DO NOT EXIST + +There is no `modules/core/commands/build.liquid` and no +`modules/core/commands/check.liquid`. The build/check phases are +APP-LEVEL — your own command directory contains them as nested partials, +e.g. `app/lib/commands/products/create/build.liquid` and `…/check.liquid`. + +```liquid +{% comment %} ✗ FAILS — no such file in core 2.1.8 {% endcomment %} +{% function object = 'modules/core/commands/build', object: params %} + +{% comment %} ✓ Correct — your own build partial {% endcomment %} +{% function object = 'commands/products/create/build', object: params %} +``` + +The only top-level command runner the core module ships is +`modules/core/commands/execute`. Generate the build/check/execute trio +with `pos-cli generators run crud --resource `. + +--- + +## Validator Renames (legacy → modern) + +If you copied validator config from older docs, these will fail at +function-resolve time: -### "Liquid error: modules/core/commands/build not found" +| Legacy name | Modern replacement | Notes | +|------------------|----------------------------------|-------| +| `numericality` | `number` | options renamed `greater_than`/`less_than` → `gt`/`gte`/`lt`/`lte`/`eq`/`ne` | +| `format` | `matches` | option renamed `pattern` → `regexp` | +| `confirmation` | `equal` with `to: ''`| explicit pair-comparison | +| `inclusion` | `included` with `in: [...]` | option renamed `values` → `in` | -**Cause:** The core module is not installed, or the deployment did not include the module files. +The validator files at `modules/core/lib/validations/` are the canonical +source. Calling `'modules/core/lib/validations/format'` (with no file +behind it) is the same kind of failure as calling phantom build/check. -**Solution:** Run `pos-cli modules install core` and redeploy with `pos-cli deploy`. +--- + +## Validators Take Direct Args, Not a JSON Hash + +Modern validators are CALLED INDIVIDUALLY with named parameters, not +config-driven through a single `validators` array passed to a checker: + +```liquid +{% comment %} ✓ Modern shape — chain validators in your check partial {% endcomment %} +{% function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'title', object: object %} +{% function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 %} +``` + +```liquid +{% comment %} ✗ Legacy shape — no longer supported {% endcomment %} +{% assign validators = [ + { "name": "presence", "property": "title" }, + { "name": "numericality", "property": "price", "options": { "greater_than": 0 } } +] %} +{% function object = 'modules/core/commands/check', + object: object, validators: validators %} +``` + +--- + +## Common Errors ### "object.errors is always blank even with invalid data" -**Cause:** The validators array is malformed, empty, or the property names do not match the object keys. +**Cause:** Your `check` partial is not threading the contract `c` through +each validator call. -**Solution:** Verify the JSON validators array is valid. Ensure each `"property"` value exactly matches a key in the object passed to `build`. Use `{% log validators, type: 'debug' %}` to inspect. +**Solution:** Each validator returns a contract; pass the result back as +the `c:` argument of the next call. At the end, set `object.errors = c` +and `object.valid = c == empty`. See patterns.md for the canonical shape. ### "Uniqueness validator fails with 'table not found'" -**Cause:** The `table` option references a schema table name that does not exist or has a typo. +**Cause:** The `table` option does not match a schema name. -**Solution:** Check your `app/schema/` directory for the correct table name. The table value must match the filename without the `.yml` extension. +**Solution:** Check `app/schema/.yml`. The table value must equal +the filename without `.yml`. The `scope` option, if used, is a list of +field names that further narrow uniqueness (e.g. unique-per-tenant). ### "Execute command returns nil instead of the created record" -**Cause:** The `selection` parameter does not match the GraphQL mutation's return field name. +**Cause:** The `selection:` parameter doesn't match the mutation's +top-level result field. The default is `'record'`; record CRUD ops +typically use `'record_create'`, `'record_update'`, `'record_delete'`. -**Solution:** If your mutation uses `record_create`, set `selection: 'record_create'`. For updates use `record_update`. For deletes use `record_delete`. Check the mutation file to confirm the exact field name. +**Solution:** Inspect the mutation file (`app/graphql/<...>.graphql`) and +match the top-level alias literally. ### "Events are published but consumers never fire" -**Cause:** The event consumer is not registered correctly, or the event type string does not match between publisher and consumer. +**Cause:** Consumer file path or `type` string mismatch. -**Solution:** Verify the consumer file exists in the correct path. Ensure the event `type` string is identical in both the `publish` call and the consumer registration. Check logs for consumer errors. +**Solution:** Verify the consumer file exists under `app/lib/events//...`. +The `type` argument to `events/publish` must match exactly. Tail the +instance log for consumer errors. ### "Flash message appears on wrong page or not at all" -**Cause:** The `from` parameter in `session/set` does not match the current page path, or the flash is cleared before being displayed. +**Cause:** `from:` does not match the current page path, or the flash is +cleared before display. -**Solution:** Pass `from: context.location.pathname` when setting the flash. Read and display the flash in your layout before any partials clear it. Ensure `session/clear` is called after rendering, not before. +**Solution:** Pass `from: context.location.pathname` when setting. Read + +clear the flash in your layout once per request. The `from` value lets +the flash auto-clear on subsequent unrelated navigation. ### "Validation error messages are not translated" -**Cause:** Validators return default English error messages. Translation must be handled in the display layer. +**Cause:** Validators emit translation KEYS (e.g. +`'modules/core/validation.matches'`); translation happens in your display +layer. -**Solution:** Map error keys to translation keys in your form partial. The errors hash uses field names as keys and arrays of error messages as values. +**Solution:** In the form partial, run each error message through `| t`, +or look up custom translations in your locale files. ### "Cannot override a core module file" -**Cause:** The override file is placed in the wrong path. Overrides must mirror the exact path structure. +**Cause:** Override placed at the wrong path. + +**Solution:** Override path mirrors the module tree under +`app/modules/core/public/...`. The path after `public/` must be identical. -**Solution:** Copy from `modules/core/public/lib/...` to `app/modules/core/public/lib/...`. The relative path after `public/` must be identical. +--- ## Limits -| Resource | Limit | Notes | -|---------------------------------|--------------------|-------------------------------------------------| -| Validators per check call | No hard limit | Performance degrades beyond ~20 validators | -| Session value size | 4 KB | Per key; use database for larger data | -| Event payload size | 1 MB | Keep payloads lean; pass IDs not full objects | -| Events published per request | No hard limit | Each event adds latency; batch where possible | -| Nested command depth | 3 levels | Commands calling commands calling commands | -| GraphQL mutation file path | 255 characters | Relative to `app/graphql/` | +| Resource | Limit | Notes | +|---------------------------|------------------|----------------------------------------| +| Validators per check | No hard limit | Performance degrades beyond ~20 | +| Session value size | 4 KB | Per key; use a record for larger data | +| Event payload size | 1 MB | Pass IDs not full objects when possible| +| Nested command depth | ~3 levels | Commands calling commands calling … | +| GraphQL mutation path | 255 characters | Relative to `app/graphql/` | ## See Also -- [Core Overview](README.md) -- introduction and key concepts -- [Core Configuration](configuration.md) -- installation and setup -- [Core API](api.md) -- all available functions -- [Core Patterns](patterns.md) -- real-world usage examples -- [Core Advanced](advanced.md) -- custom validators and edge cases +- [Core Overview](README.md) +- [Core API](api.md) +- [Core Configuration](configuration.md) +- [Core Patterns](patterns.md) +- [Core Advanced](advanced.md) diff --git a/src/data/references/modules/core/patterns.md b/src/data/references/modules/core/patterns.md index db14e28..8d21cc9 100644 --- a/src/data/references/modules/core/patterns.md +++ b/src/data/references/modules/core/patterns.md @@ -1,26 +1,22 @@ -# pos-module-core -- Patterns & Best Practices +# pos-module-core — Patterns -Common workflows and real-world patterns for the core module. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The +> build/check phases live in your APP commands, not in +> `modules/core/commands/`. Only `commands/execute` runs at the top level. ## Standard Create Command -The most common pattern: validate input and create a record. +Three files: the orchestrator, your build, your check. The orchestrator +calls them in order, then `modules/core/commands/execute` for the +mutation. Generated automatically by `pos-cli generators run crud +--resource `. ```liquid {% comment %} app/lib/commands/products/create.liquid {% endcomment %} {% liquid - function object = 'modules/core/commands/build', object: params - - assign validators = [ - { "name": "presence", "property": "title" }, - { "name": "presence", "property": "price" }, - { "name": "numericality", "property": "price", "options": { "greater_than": 0 } }, - { "name": "length", "property": "title", "options": { "minimum": 3, "maximum": 255 } }, - { "name": "uniqueness", "property": "slug", "options": { "table": "product" } } - ] - function object = 'modules/core/commands/check', object: object, validators: validators - - if object.errors != blank + function object = 'commands/products/create/build', object: params + function object = 'commands/products/create/check', object: object + if object.valid == false return object endif @@ -29,33 +25,66 @@ The most common pattern: validate input and create a record. selection: 'record_create', object: object - function _ = 'modules/core/commands/events/publish', type: 'product_created', object: object + function _ = 'modules/core/commands/events/publish', + type: 'product_created', object: object return object %} ``` +```liquid +{% comment %} app/lib/commands/products/create/build.liquid {% endcomment %} +{% doc %} + @param {object} object - raw input (typically context.params) +{% enddoc %} +{% liquid + assign object = object | hash_merge: valid: true, errors: empty + return object +%} +``` + +```liquid +{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %} +{% doc %} + @param {object} object - object to validate +{% enddoc %} +{% liquid + assign c = object.errors | default: empty + + function c = 'modules/core/lib/validations/presence', + c: c, field_name: 'title', object: object + + function c = 'modules/core/lib/validations/number', + c: c, field_name: 'price', object: object, gt: 0 + + function c = 'modules/core/lib/validations/length', + c: c, field_name: 'title', object: object, min: 3, max: 255 + + function c = 'modules/core/lib/validations/uniqueness', + c: c, field_name: 'slug', object: object, table: 'product' + + assign object.errors = c + assign object.valid = c == empty + return object +%} +``` + ## Standard Update Command -Update differs from create: you load the existing record first, merge changes, then validate. +Update loads the existing record first, merges, validates, executes. ```liquid {% comment %} app/lib/commands/products/update.liquid {% endcomment %} {% liquid - graphql result = 'products/find', id: id - assign existing = result.records.results.first + function existing = 'queries/products/find', id: id if existing == blank - assign error = { "errors": { "base": ["Record not found"] } } - return error + return { valid: false, errors: { base: ['Record not found'] } } endif assign params['id'] = id - function object = 'modules/core/commands/build', object: params - - assign validators = [{ "name": "presence", "property": "title" }, { "name": "numericality", "property": "price", "options": { "greater_than": 0 } }] - function object = 'modules/core/commands/check', object: object, validators: validators - - if object.errors != blank + function object = 'commands/products/update/build', object: params, existing: existing + function object = 'commands/products/update/check', object: object + if object.valid == false return object endif @@ -70,19 +99,20 @@ Update differs from create: you load the existing record first, merge changes, t ## Standard Delete Command -Delete is simpler -- typically no validation needed. +Delete usually skips check (the page-level auth helper already gated it). ```liquid {% comment %} app/lib/commands/products/delete.liquid {% endcomment %} {% liquid - assign object = { "id": id } + assign object = { id: id } function object = 'modules/core/commands/execute', mutation_name: 'products/delete', selection: 'record_delete', object: object - function _ = 'modules/core/commands/events/publish', type: 'product_deleted', object: object + function _ = 'modules/core/commands/events/publish', + type: 'product_deleted', object: object return object %} @@ -90,8 +120,6 @@ Delete is simpler -- typically no validation needed. ## Calling Commands from Pages -Pages call commands and handle the result: - ```liquid {% comment %} app/views/pages/products/create.liquid {% endcomment %} --- @@ -99,36 +127,41 @@ slug: products method: post --- {% liquid - function profile = 'modules/user/queries/user/current' - include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'products.create' + graphql current_user = 'modules/user/queries/user/current' + function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, do: 'products.create' - function result = 'lib/commands/products/create', params: context.params + function result = 'commands/products/create', params: context.params - if result.errors != blank + if result.valid == false render 'products/new', errors: result.errors, params: context.params break endif - function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'Product created', from: context.location.pathname + function _ = 'modules/core/commands/session/set', + key: 'sflash', value: 'Product created', + from: context.location.pathname redirect_to '/products' %} ``` -## Flash Message Pattern +Note: helpers use `{% function %}` and `do:` (modernized canonical) — never +`{% include %}` or `with_action:`. -Set a flash message before redirect, then display it on the target page via the layout: +## Flash Message Pattern ```liquid -{% comment %} In a page: set flash then redirect {% endcomment %} +{% comment %} Set flash before redirect {% endcomment %} {% liquid function _ = 'modules/core/commands/session/set', - key: 'sflash', value: 'Item saved successfully', from: context.location.pathname + key: 'sflash', value: 'Item saved.', + from: context.location.pathname redirect_to '/items' %} ``` ```liquid -{% comment %} In layout or partial: read and display flash {% endcomment %} +{% comment %} Layout or shared partial: read + clear {% endcomment %} {% liquid function flash = 'modules/core/commands/session/get', key: 'sflash' if flash != blank @@ -138,63 +171,56 @@ Set a flash message before redirect, then display it on the target page via the %} ``` -## Event Publishing Pattern - -Publish events after successful mutations for decoupled side effects: +## Event Publishing ```liquid -{% comment %} After creating an order {% endcomment %} {% function _ = 'modules/core/commands/events/publish', - type: 'order_created', - object: order -%} + type: 'order_created', object: order %} ``` -Event consumers are defined in `app/lib/consumers/` and registered in schema. They run asynchronously. - -## Redirect with Notice Pattern +Subscribers (defined in `app/lib/events/`) consume the event asynchronously. +Use `events/broadcast` for fan-out to multiple type-prefixed consumers. -Use the `redirect_to` helper for a one-liner: +## Redirect with Notice (one-liner) ```liquid -{% include 'modules/core/helpers/redirect_to', - url: '/products', notice: 'app.product_created' -%} +{% function _ = 'modules/core/helpers/redirect_to', + url: '/products', notice: 'app.product_created' %} ``` -This sets the flash notice using the translation key and redirects in a single call. - -## Validation Error Display Pattern +Sets the `sflash` session value via the translation key, then redirects. -Pass errors to the form partial and render them: +## Validation Error Display ```liquid {% comment %} In the form partial {% endcomment %} {% if errors != blank %} -
      +
      {% for error in errors %} -

      {{ error[0] }}: {{ error[1] | join: ", " }}

      +

      {{ error[0] }}: {{ error[1] | join: ', ' }}

      {% endfor %}
      {% endif %} ``` +(`pos-toast-*` is the canonical notification style; see common-styling.) + ## Best Practices -1. **Always use the command pattern** -- never call GraphQL mutations directly from pages -2. **Validate before executing** -- always call `check` before `execute` -3. **Return early on errors** -- check `object.errors` immediately after `check` -4. **Publish events for side effects** -- do not send emails or notifications inside commands; use events -5. **Use translation keys for flash** -- pass `'app.some_key'` not raw strings in production -6. **Keep validators in the command** -- do not scatter validation logic across pages -7. **One command per operation** -- separate create, update, delete into individual partials +1. Use the command pattern — never call mutations directly from pages. +2. Validate before executing — `check` runs before `execute`. +3. Return early on `object.valid == false`. +4. Publish events for side effects (emails, notifications, audit logs). +5. Use translation keys for flash messages, not raw strings. +6. Keep validators inside the `check` partial; pages stay thin. +7. One command per operation (create / update / delete are separate files). +8. Use `pos-cli generators run crud --resource ` to scaffold the + build/check/execute trio with the canonical wiring. ## See Also -- [Core Overview](README.md) -- introduction and key concepts -- [Core API](api.md) -- all available functions -- [Core Configuration](configuration.md) -- installation and setup -- [Core Gotchas](gotchas.md) -- common errors and limits -- [Core Advanced](advanced.md) -- custom validators and overrides -- [Pages Patterns](../../pages/patterns.md) -- how pages call commands -- [Events & Consumers](../../events-consumers/README.md) -- event consumer setup +- [Core Overview](README.md) +- [Core API](api.md) — validator family + option names +- [Core Configuration](configuration.md) +- [Core Gotchas](gotchas.md) — esp. "core/commands/build doesn't exist" +- [Core Advanced](advanced.md) — custom validators, event chaining diff --git a/src/data/references/modules/user/README.md b/src/data/references/modules/user/README.md index 57d89cc..2a6d381 100644 --- a/src/data/references/modules/user/README.md +++ b/src/data/references/modules/user/README.md @@ -1,8 +1,11 @@ # pos-module-user -The user module provides authentication, role-based access control (RBAC), and OAuth2 integration. +The user module provides authentication, role-based access control (RBAC), +profile management, and OAuth record CRUD. Provider-specific OAuth flows +(GitHub, etc.) live in optional companion modules like `oauth_github`. **Required module** — must be installed in every project. +Compatible with pos-cli 6.0.7+ (modernized canonical syntax). ## Install @@ -12,80 +15,86 @@ pos-cli modules install user ## Documentation -Full docs: https://github.com/Platform-OS/pos-module-user +- Live API surface: `module_info(name: 'user', section: 'api')` — scanned + from disk, always current. +- Upstream: https://github.com/Platform-OS/pos-module-user -## Key Functions +## Key Calls -### Get Current User +All helpers use `{% function %}` and the `do:` parameter. The legacy +`{% include %}` and `with_action:` forms are rejected by the LSP. +### Get Current User ```liquid -{% function profile = 'modules/user/queries/user/current' %} +{% graphql current_user = 'modules/user/queries/user/current' %} ``` -**NEVER use `context.current_user` directly.** +**NEVER use `context.current_user` directly** — helpers expect the +profile-shaped object this query returns. ### Check Permission (returns boolean) - ```liquid {% function can = 'modules/user/helpers/can_do', - requester: profile, - do: 'products.create' -%} + requester: current_user, + do: 'products.create' %} ``` -### Enforce Permission (403 if denied) - +### Enforce Permission (403 if denied; redirect anonymous to login) ```liquid -{% include 'modules/user/helpers/can_do_or_unauthorized', - requester: profile, - do: 'admin.view', - redirect_anonymous_to_login: true -%} +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + do: 'admin_pages.view', + redirect_anonymous_to_login: true %} ``` ### Redirect If Denied - ```liquid -{% include 'modules/user/helpers/can_do_or_redirect', - requester: profile, - do: 'orders.view', - return_url: '/login' -%} +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, + do: 'orders.view', + return_url: '/sign-in' %} ``` -## Built-in Roles +## Built-in Roles (shipped permissions hash) | Role | Description | |------|-------------| | `anonymous` | Unauthenticated visitors | | `authenticated` | Any logged-in user | -| `superadmin` | Bypasses ALL permission checks | +| `member` | Authenticated user with profile | +| `admin` | Admin-pages + user management | +| `superadmin` | Impersonation incl. other superadmins | ## Custom Roles & Permissions -Override the permissions file: +Override the role-permissions query at the canonical module-override path: -```bash -mkdir -p app/modules/user/public/lib/queries/role_permissions -cp modules/user/public/lib/queries/role_permissions/permissions.liquid \ - app/modules/user/public/lib/queries/role_permissions/permissions.liquid ``` - -Define roles: +app/modules/user/public/lib/queries/role_permissions/permissions.liquid +``` ```liquid -{% assign data = { - "admin": ["admin.view", "users.manage", "products.create", "products.update", "products.delete"], - "editor": ["article.create", "article.update"], - "viewer": ["article.view", "products.view"], - "superadmin": [] -} %} +{% parse_json data %} +{ + "anonymous": ["sessions.create", "users.register"], + "authenticated": ["sessions.destroy", "oauth.manage"], + "editor": ["posts.create", "posts.update"], + "admin": ["admin_pages.view", "users.manage", "posts.create", "posts.update", "posts.delete"], + "superadmin": [] +} +{% endparse_json %} {% return data %} ``` +`superadmin` MAY have an empty list — the helper short-circuits to allow +for that role unconditionally. + ## Rules -- NEVER use `context.current_user` directly -- NEVER use `authorization_policies/` directory -- Always get user via module query -- Always check permissions via module helpers +- ALWAYS pull `current_user` via `modules/user/queries/user/current`. +- ALWAYS use `{% function %}` for helpers (never `{% include %}`). +- ALWAYS use `do:` (never `with_action:`). +- NEVER render `app/authorization_policies/` partials directly — go through + a `can_do*` helper. +- For per-entity rules (ownership/tenancy), pass `access_callback:` — + see advanced.md. diff --git a/src/data/references/modules/user/advanced.md b/src/data/references/modules/user/advanced.md index 947e72c..fb8847a 100644 --- a/src/data/references/modules/user/advanced.md +++ b/src/data/references/modules/user/advanced.md @@ -1,157 +1,157 @@ -# modules/user - Advanced Configuration +# modules/user - Advanced Topics -## Custom Permission System +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). -### Override Permission Logic -Create custom permission rules in `permissions.liquid`: +## Custom Permission Logic via `access_callback` + +For per-entity authorization beyond simple role→action mapping, pass an +`access_callback` to the helper. The callback is your own helper file; it +receives `requester`, `entity`, and `do`, and must return a boolean. ```liquid -# app/lib/modules/user/permissions.liquid - -{% assign action = include.action %} -{% assign user = include.user %} - -{% case action %} - {% when 'edit_post' %} - {% if post.author_id == user.id %} - {% assign can_do = true %} - {% endif %} - {% when 'delete_post' %} - {% if user.roles contains 'moderator' %} - {% assign can_do = true %} - {% endif %} -{% endcase %} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% graphql post = 'queries/posts/find', id: context.params.id %} + +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + entity: post, + do: 'posts.edit', + access_callback: 'helpers/posts/access' %} ``` -### Role Hierarchies -Implement role inheritance: +Your callback at `app/lib/helpers/posts/access.liquid`: ```liquid -{% assign role = current_user.roles.first %} - -{% case role %} - {% when 'superadmin' %} - {% assign permissions = 'create_user,delete_user,manage_settings' | split: ',' %} - {% when 'admin' %} - {% assign permissions = 'create_user,edit_content' | split: ',' %} - {% when 'moderator' %} - {% assign permissions = 'edit_content,delete_comments' | split: ',' %} -{% endcase %} +{% doc %} + @param {object} requester + @param {object} entity + @param {string} do +{% enddoc %} +{% liquid + if requester.roles contains 'admin' + return true + endif + if do == 'posts.edit' and entity.author_id == requester.id + return true + endif + return false +%} ``` +The callback **wins** over the role-permissions map: when present, +`can_do` skips the permissions hash and uses your decision. Use this for +ownership / tenancy / time-windowed access — everything else stays in the +hash override. + ## Multi-Tenant Authorization -### Tenant Context -Add tenant awareness to permissions: +Tenant isolation belongs in your callback (above), not in the permissions +map. Permissions answer "what *kind* of action," ownership/tenancy +answers "this *specific* entity." ```liquid -{% assign tenant_id = site.tenant_id %} - -{% include 'modules/user/helpers/can_do' - with_action: 'edit_content' - with_context: tenant_id -%} +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + entity: tenant_resource, + do: 'tenant.read', + access_callback: 'helpers/tenancy/owns' %} ``` -### Tenant Isolation -Ensure cross-tenant data protection: +Always pair it with tenant-scoped GraphQL queries (filter by `tenant_id`) +so the model layer never returns the wrong tenant's rows in the first place. -```graphql -query UserContent($tenant_id: ID!) { - content(filter: { tenant_id: $tenant_id }) { - id - title - } -} -``` - -## Advanced OAuth2 Setup +## OAuth: Multiple Providers -### Multiple Provider Configuration -Support multiple OAuth2 providers: +The user module ships only the OAuth-record CRUD. Concrete provider flows +live in companion modules (`oauth_github`, etc.). To enumerate the providers +that are linkable for the current user, call: ```liquid -{% liquid - assign providers = 'google,github,linkedin' | split: ',' -%} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function available = 'modules/user/helpers/get_available_oauth_providers', + user_id: current_user.id %} -{% for provider in providers %} - - Sign in with {{ provider | capitalize }} +{% for provider in available %} + + Sign in with {{ provider.name | capitalize }} {% endfor %} ``` -### Custom Provider Integration -Add custom OAuth2 provider: - -```graphql -mutation ConfigureOAuthProvider($name: String!, $config: JSON!) { - oauth_provider_create(data: { - name: $name - client_id: $config.client_id - client_secret: $config.client_secret - }) { - oauth_provider { id } - } -} +`get_available_oauth_providers` returns the providers the instance has +configured (via constants) but the user has not yet linked. + +To list the providers already linked to a user: + +```liquid +{% function linked = 'modules/user/helpers/get_assigned_oauth_providers', + user_id: current_user.id %} ``` +To unlink a provider, delete the OAuth record via +`graphql/oauth/delete.graphql`. + ## Session Management -### Custom Session Timeout -Implement session expiration: +The session lifecycle is owned by `commands/session/`. The user module ships: -```liquid -{% assign session_duration = 3600 %} -{% assign session_created = current_user.session_created_at %} -{% assign now = 'now' | date: '%s' | plus: 0 %} -{% assign elapsed = now | minus: session_created %} +- `commands/session/create.liquid` — sign-in flow entry point +- `commands/session/destroy.liquid` — sign-out +- `commands/authentication_links/create.liquid` — magic-link flow -{% if elapsed > session_duration %} - +Custom session timeouts belong in your layout — check +`current_user.last_active_at` (or your own `session.last_seen` constant) and +call `commands/session/destroy` when stale. + +```liquid +{% graphql current_user = 'modules/user/queries/user/current' %} +{% if current_user %} + {% assign now = 'now' | date: '%s' | plus: 0 %} + {% assign last = current_user.last_active_at | date: '%s' | plus: 0 %} + {% assign elapsed = now | minus: last %} + {% if elapsed > 1800 %} + {% function _ = 'modules/user/commands/session/destroy' %} + {% endif %} {% endif %} ``` -### Concurrent Session Control -Limit concurrent logins: +## 2FA Hooks (user 5.x) -```liquid -{% graphql active_sessions = 'queries/user/active_sessions' %} +The 2FA partial set lives at `views/partials/2fa/` and is rendered from the +shipped pages flow. To integrate 2FA into a custom sign-in screen, render +the shipped partials rather than rebuilding: -{% if active_sessions.size >= max_concurrent_sessions %} - -{% endif %} +```liquid +{% render 'modules/user/2fa/setup' %} +{% render 'modules/user/2fa/verify' %} ``` -## Audit Logging +The 2FA secret is stored on the user profile. Verification is a normal +session-create flow with the OTP attached — the module's +`commands/session/create` already handles the OTP step. + +## Audit Logging Authorization -### Track Authorization Events -Log all authorization checks: +The user module does not ship an audit log. If you need one, log from your +own callback: ```liquid -{% include 'modules/user/helpers/can_do' - with_action: 'delete_sensitive_data' - with_audit: true +{% liquid + function r = 'commands/audit_log/create', + user_id: requester.id, + action: do, + entity_id: entity.id, + granted: result + return result %} ``` -### Create Audit Entry -```graphql -mutation LogAuthorizationEvent($action: String!, $result: Boolean) { - audit_log_create(data: { - action: $action - result: $result - user_id: $user_id - timestamp: "now" - }) { - audit_log { id } - } -} -``` +Avoid wrapping `can_do` itself in a logger — log inside your `access_callback` +so you only record decisions you actually made. ## See Also - configuration.md - Basic setup -- api.md - API reference +- api.md - API surface overview - patterns.md - Common patterns - gotchas.md - Common mistakes +- prerequisites.md - Required setup before using this module diff --git a/src/data/references/modules/user/api.md b/src/data/references/modules/user/api.md index 04d5a8e..9ec71c8 100644 --- a/src/data/references/modules/user/api.md +++ b/src/data/references/modules/user/api.md @@ -1,22 +1,23 @@ # modules/user - API Reference -The live API surface (call signatures, required/optional params, return types) -is exposed via `module_info(name: 'user', section: 'api')` and scanned directly -from the installed module's source. This file provides narrative notes and -GraphQL context that a disk scan cannot infer. +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The +> live API surface (call paths, required/optional params, return types) +> is the source of truth — call `module_info(name: 'user', section: 'api')`, +> which is scanned from disk and always current. This file provides +> narrative notes + GraphQL context that the scan cannot infer. ## GraphQL Schema Highlights ### Current User -Fetch the authenticated user's information server-side: +Fetch the authenticated user's profile server-side: ```liquid {% graphql current_user = 'modules/user/queries/user/current' %} {{ current_user.email }} ``` -Underlying operation: +Underlying operation (from `graphql/user/current.graphql`): ```graphql query CurrentUser { @@ -30,79 +31,98 @@ query CurrentUser { } ``` -### User by ID +### Find User by ID / email -```graphql -query GetUser($id: ID!) { - user(id: $id) { - id - email - created_at - roles { name } - } -} +The user-find query lives at `graphql/user/find.graphql` and accepts both +`$id` and `$email` filters: + +```liquid +{% graphql found = 'modules/user/queries/user/find', id: id %} ``` -## Mutations +The scan exposes the full param list and return shape under +`module_info → queries → 'queries/user/find'`. -### Update User Profile +## OAuth (record CRUD only) -```graphql -mutation UpdateProfile($email: String, $first_name: String) { - user_update(data: { - email: $email - first_name: $first_name - }) { - user { id email } - } -} -``` +The `user` module ships only the OAuth-record schema and CRUD ops: -### Create User +- `graphql/oauth/create.graphql` — link a provider account to a user +- `graphql/oauth/delete.graphql` — unlink +- `graphql/oauth/find_by_sub.graphql` — find a record by provider + sub +- `graphql/oauth/find_by_user_id.graphql` — list a user's linked providers -```graphql -mutation CreateUser($email: String!, $password: String!) { - user_create(data: { - email: $email - password: $password - }) { - user { id email } - } -} -``` +The actual provider sign-in flows (GitHub, etc.) live in companion modules +(`oauth_github`, ...). If `oauth_github` is not installed, the +`views/pages/oauth/` callback pages are inert. -## Authorization Helpers (use `{% function %}`, NOT `{% include %}`) +## Authorization Helpers — canonical `{% function %}` form -platformOS has deprecated `{% include %}` for app code. All user-module -authorization helpers MUST be invoked via `{% function %}`. The scan-derived -`module_info(name: 'user', section: 'api')` response contains the exact call -signature for each helper — always prefer that over examples here. +All `can_do*` helpers expect a profile-shaped `requester` (from the +`current_user` query) and a `do:` action string. The legacy +`{% include %}` and `with_action:` forms are rejected by the LSP. -### Permission check +### Permission check (returns boolean) ```liquid -{% function allowed = 'modules/user/helpers/can_do', requester: context.current_user, do: 'delete_post' %} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function allowed = 'modules/user/helpers/can_do', + requester: current_user, + do: 'posts.delete' %} {% if allowed %}...{% endif %} ``` ### Redirect unauthorized users ```liquid -{% function _ = 'modules/user/helpers/can_do_or_redirect', requester: context.current_user, do: 'admin_panel' %} +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, + do: 'admin_pages.view', + return_url: '/sign-in' %} +``` + +### 403 / redirect-anonymous + +```liquid +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + do: 'admin.users.manage', + redirect_anonymous_to_login: true %} ``` -### Return 403 Forbidden for unauthorized users +### Per-entity authorization via `access_callback` + +For per-entity rules (ownership, tenancy), pass an `access_callback`: + +```liquid +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + entity: post, + do: 'posts.edit', + access_callback: 'helpers/posts/access' %} +``` + +The callback is invoked with `requester`, `entity`, `do` and returns a +boolean. When present, it WINS over the role-permissions hash (see +advanced.md). + +## OAuth Provider Helpers ```liquid -{% function _ = 'modules/user/helpers/can_do_or_unauthorized', requester: context.current_user, do: 'sensitive_action' %} +{% function linked = 'modules/user/helpers/get_assigned_oauth_providers', + user_id: current_user.id %} +{% function available = 'modules/user/helpers/get_available_oauth_providers', + user_id: current_user.id %} ``` -MUST NOT use `{% include 'modules/user/helpers/...' %}` — the module's public -interface uses `{% function %}` with `requester` and `do` as required params. +`available` returns providers the instance has configured (via constants) +that the user has not yet linked. `linked` returns existing OAuth records +for the user. ## See Also - `configuration.md` — setup and configuration - `patterns.md` — common usage patterns - `gotchas.md` — common mistakes -- `advanced.md` — advanced techniques +- `advanced.md` — advanced techniques (callbacks, 2FA, sessions) +- `prerequisites.md` — required setup before using this module diff --git a/src/data/references/modules/user/configuration.md b/src/data/references/modules/user/configuration.md index f19fb84..b81750d 100644 --- a/src/data/references/modules/user/configuration.md +++ b/src/data/references/modules/user/configuration.md @@ -1,75 +1,98 @@ # modules/user - Configuration +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). + ## Overview -The `modules/user` is a required module that handles authentication, authorization, and user management. It provides role-based access control (RBAC) and OAuth2 integration. -## Installation +`modules/user` is the authentication, authorization, and profile module. It +provides role-based access control (RBAC), OAuth record CRUD (the actual +provider flows live in optional companion modules like `oauth_github`), and +the standard user-management page set (sign in, sign up, profiles, password +reset, 2FA). -The user module is required and installed by default. No additional setup steps are needed. +## Installation -## Core Configuration +`user` is a required module on most instances. Confirm presence: -### User Context Access -Get the current user in your Liquid code: -```liquid -{% graphql current_user = 'modules/user/queries/user/current' %} +```bash +ls modules/user/pos-module.json ``` -### Roles Setup -The module provides three default roles: -- **anonymous**: Unauthenticated users -- **authenticated**: Logged-in users -- **superadmin**: Full system access +Module dependencies (per `pos-module.json`): `core`, `common-styling`, and +optional `oauth_github`. Re-run `pos-cli modules version user` if +`template-values.json` and `pos-module.json` drift (the dashboard surfaces +this via `manifest_warnings`). + +## Default Roles + +The shipped `permissions.liquid` query enumerates these: + +- **anonymous** — unauthenticated visitors +- **authenticated** — logged-in users (any role) +- **member** — basic user with a profile +- **admin** — admin-pages access + user management +- **superadmin** — impersonation rights including superadmin impersonation + +These cover the module's own pages. Apps almost always need additional +roles + permissions, which means overriding `permissions.liquid`. + +## Adding Custom Roles + Permissions + +Create the override at the canonical app-relative path +`app/modules/user/public/lib/queries/role_permissions/permissions.liquid` and return a hash +mapping role-name → list of permission strings: -### Custom Roles -Create custom roles by overriding `permissions.liquid`: ```liquid -# app/lib/modules/user/permissions.liquid -{% case role %} - {% when 'moderator' %} - can_moderate: true - {% when 'content-editor' %} - can_edit_content: true -{% endcase %} +{% parse_json data %} +{ + "anonymous": ["sessions.create", "users.register"], + "authenticated": ["sessions.destroy", "oauth.manage"], + "member": ["profile.manage"], + "editor": ["posts.create", "posts.update"], + "admin": ["admin_pages.view", "admin.users.manage", "users.impersonate", "posts.create", "posts.update", "posts.delete"], + "superadmin": ["users.impersonate_superadmin"] +} +{% endparse_json %} +{% return data %} ``` -## OAuth2 Configuration +Include EVERY role you assign — a role missing from this hash gets denied +silently for every action. -### Provider Setup -Configure OAuth2 providers in your instance: +## OAuth Provider Configuration -```yaml -oauth_providers: - - provider: google - client_id: YOUR_CLIENT_ID - client_secret: YOUR_CLIENT_SECRET - - provider: github - client_id: YOUR_CLIENT_ID - client_secret: YOUR_CLIENT_SECRET -``` +The `user` module ships only the OAuth-record schema and CRUD operations. +Provider flows are in companion modules: -### Environment Variables -Set credentials via environment: -``` -GOOGLE_CLIENT_ID=xxx -GOOGLE_CLIENT_SECRET=yyy -GITHUB_CLIENT_ID=xxx -GITHUB_CLIENT_SECRET=yyy -``` +- `oauth_github` — GitHub OAuth callback + linking flow. +- (other providers ship as separate modules where available) -## Permission Helpers +If you need a provider not yet packaged, look at `oauth_github` for the +shape: it consumes the `user` module's `graphql/oauth/{create,delete}.graphql` +mutations to persist linked-account records. + +Provider credentials are read from instance constants. Set them via +`pos-cli constants set ` rather than committing them to +`pos-module.json`. + +## Permission Helpers (canonical call form) -### Check Permissions -Use the permission helper to verify access: ```liquid -{% include 'modules/user/helpers/can_do' with_action: 'edit_post' %} -{% if can_do %} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function can = 'modules/user/helpers/can_do', + requester: current_user, + do: 'posts.edit' %} +{% if can %} {% endif %} ``` +The legacy `{% include %}` call is deprecated — the LSP rejects it as +`DeprecatedTag`. Always use `{% function %}`. + ## See Also -- api.md - API endpoints and queries +- api.md - API surface overview - patterns.md - Common usage patterns - gotchas.md - Common mistakes - advanced.md - Advanced configuration +- prerequisites.md - Required setup before using this module diff --git a/src/data/references/modules/user/gotchas.md b/src/data/references/modules/user/gotchas.md index b48c4fd..c1e0982 100644 --- a/src/data/references/modules/user/gotchas.md +++ b/src/data/references/modules/user/gotchas.md @@ -1,59 +1,90 @@ # modules/user - Common Gotchas -## Critical: Custom Permission Actions Silently Fail Without permissions.liquid +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). Helpers use +> `{% function %}` and the `do:` parameter; the LSP rejects legacy +> `{% include %}` calls and `with_action:` aliases. -Using `can_do_or_redirect`, `can_do`, or `can_do_or_unauthorized` with a custom action string -(e.g., `do: 'blog_post.create'`) will silently deny ALL users — including authenticated ones — -if `app/views/partials/permissions.liquid` does not exist. +## Critical: Custom Permission Actions Silently Fail Without an Override -There is no error. The user is simply redirected or denied with no explanation. +Calling `can_do_or_redirect`, `can_do`, or `can_do_or_unauthorized` with an +action string that isn't in the role-permissions map (e.g. `do: 'posts.edit'`) +silently denies every user — including authenticated ones. There is no +exception; the user is simply redirected or 403'd. -```liquid - -{% include 'modules/user/helpers/can_do_or_redirect' with_action: 'blog_post.create' %} +The module ships a default `permissions.liquid` query at +`modules/user/public/lib/queries/role_permissions/permissions.liquid` listing +the roles the module's own pages need (`anonymous`, `authenticated`, `admin`, +`member`, `superadmin`). To add custom permissions for your app, override that +query by creating it at the canonical app-relative path: + +``` +app/modules/user/public/lib/queries/role_permissions/permissions.liquid ``` -Fix: create `app/views/partials/permissions.liquid` that handles every action you use. -See prerequisites.md for a full setup checklist and examples. +The override must return a hash mapping role-name → list of permission +strings. See prerequisites.md for a full checklist. + +```liquid + +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, + do: 'posts.edit' %} +``` --- -## Critical: Do NOT Use Direct Context Access -Never access user context directly: +## Critical: Always Pull `current_user` via the Module Query + +Never pass `context.current_user` directly to a helper: ```liquid - -{% if context.current_user %} - -{% endif %} + +{% function _ = 'modules/user/helpers/can_do', + requester: context.current_user, do: 'posts.edit' %} ``` -Always use the module helpers: +Always go through the module query first — it returns the profile-shaped +object with `roles`, `id`, etc. populated correctly: + ```liquid - {% graphql current_user = 'modules/user/queries/user/current' %} -{% if current_user %} - -{% endif %} +{% function _ = 'modules/user/helpers/can_do', + requester: current_user, do: 'posts.edit' %} ``` -## Critical: Do NOT Use authorization_policies/ Directly -Never reference authorization policy files directly: +## Critical: Do NOT Render `app/authorization_policies/` Directly + +Never `{% render %}` a policy partial from your view: ```liquid {% render 'app/authorization_policies/admin_only' %} ``` -Always use the helpers: +Always go through a `can_do*` helper. Policies are wired into the helpers +via the role-permissions map. + ```liquid -{% render 'modules/user/helpers/can_do_or_redirect', with_action: 'admin_access' %} +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, do: 'admin.access' %} +``` + +## Critical: `{% include %}` Is Deprecated for Helpers — LSP Rejects It + +The modern canonical form is `{% function %}`. The LSP `DeprecatedTag` check +flags any `{% include 'modules/user/helpers/...' %}` call. Always: + +```liquid +{% function _ = 'modules/user/helpers/can_do', + requester: current_user, do: 'posts.edit' %} ``` ## Critical: Role Assignment and Authorization Are a Three-Part Chain -`profiles/roles/append` and `can_do` look related but operate through separate mechanisms that must all be wired together. Missing any part causes silent failure. +`profiles/roles/append` and `can_do` operate through separate mechanisms +that must all be wired together. Missing any part causes silent failure. **The full chain:** @@ -73,15 +104,16 @@ profiles/roles/append (id, role) role: 'editor' %} ``` -**Step 2 — Map the role to actions in `app/views/partials/permissions.liquid`:** +**Step 2 — Map the role to actions in your override +`app/modules/user/public/lib/queries/role_permissions/permissions.liquid`:** ```liquid {% parse_json data %} { "anonymous": ["sessions.create", "users.register"], "authenticated": ["sessions.destroy"], - "editor": ["blog_posts.create", "blog_posts.update"], - "admin": ["blog_posts.create", "blog_posts.update", "blog_posts.delete", "users.manage"] + "editor": ["posts.create", "posts.update"], + "admin": ["posts.create", "posts.update", "posts.delete", "users.manage"] } {% endparse_json %} {% return data %} @@ -91,7 +123,8 @@ profiles/roles/append (id, role) ```liquid {% function _ = 'modules/user/helpers/can_do_or_unauthorized', - action: 'blog_posts.create' %} + requester: current_user, + do: 'posts.create' %} ``` **What goes wrong when any part is missing:** @@ -99,63 +132,58 @@ profiles/roles/append (id, role) | Missing | Symptom | |---------|---------| | `profiles/roles/append` never called | User has no roles — all `can_do` checks deny | -| `permissions.liquid` doesn't exist | Every `can_do` check denies everyone, no error | -| Role assigned but not in `permissions.liquid` | `can_do` denies — role name is unknown to the permission system | -| Action string mismatch (typo) | Silently denied — `"blog_post.create"` ≠ `"blog_posts.create"` | +| `permissions.liquid` override missing | Custom action denies everyone, no error | +| Role assigned but not in the override | `can_do` denies — role unknown to the map | +| Action-string typo | Silently denied — `"post.create"` ≠ `"posts.create"` | -**`can_do` does NOT check `current_user.roles` directly.** It calls `permissions.liquid`, gets the role→actions map, then checks if the current user's roles include a role that has the requested action. The role names in `profiles/roles/append` must exactly match the keys in `permissions.liquid`. +`can_do` does NOT check `current_user.roles` directly. It calls +`permissions.liquid`, gets the role→actions map, then checks whether the +current user's roles include any role that contains the requested action. --- ## Role-Based Logic Errors -### Checking Single Role -Don't check for single string: +### Don't compare `roles` to a single string +`current_user.roles` is always an array, even for a single role. + ```liquid {% if current_user.roles == 'admin' %} -``` -Use array operations: -```liquid {% if current_user.roles contains 'admin' %} ``` -## Permission Caching Issues -Permissions are checked at request time. Don't cache permission results across requests: +## Permission Caching -```liquid - -{% assign can_edit = true %} - -``` +Permissions are evaluated per-request. Do not memoize a `can` result across +unrelated parts of the page if the role/permissions change mid-request +(e.g. after `roles/append`): -Check permissions fresh each time: ```liquid - -{% render 'modules/user/helpers/can_do', with_action: 'edit_post' %} + +{% function result = 'modules/user/commands/profiles/roles/append', + id: current_user.id, role: 'editor' %} +{% function can = 'modules/user/helpers/can_do', + requester: current_user, do: 'posts.create' %} ``` ## OAuth2 Common Issues -### Missing State Parameter -Always validate OAuth state to prevent CSRF: -```liquid - - -``` +OAuth provider integrations live in the optional `oauth_github` module +(separate dependency since user 5.x). The `user` module exposes the OAuth +record CRUD (`graphql/oauth/{create,delete,find_by_sub,find_by_user_id}.graphql`) +and the helper that lists assigned providers +(`helpers/get_assigned_oauth_providers`). -### Token Expiration -Handle expired tokens gracefully: -```liquid -{% if user.oauth_token_expired %} - -{% endif %} -``` +If `oauth_github` is not installed, the OAuth pages under +`views/pages/oauth/` are inert — the callback simply has no provider to talk +to. Don't pretend the user module ships the GitHub flow on its own. ## Password Reset Gotchas -Don't expose user existence through password resets: + +Don't expose user existence through reset responses: ```liquid @@ -165,12 +193,27 @@ Don't expose user existence through password resets: Email not found {% endif %} - + If that email exists, you'll receive a reset link. ``` +## 2FA Partials (new in user 5.x) + +`views/partials/2fa/` ships set-up, verify, and disable partials. They are +rendered from the user pages flow — your app rarely needs to render them +directly. If you ARE customizing the 2FA flow, render the shipped partials +rather than building from scratch: + +```liquid +{% render 'modules/user/2fa/setup' %} +``` + +The 2FA storage is in the user profile; verifying it goes through +`commands/session/...` rather than a separate 2FA-only command. + ## See Also - configuration.md - Setup instructions - api.md - API reference - patterns.md - Correct patterns - advanced.md - Advanced techniques +- prerequisites.md - Required setup before using this module diff --git a/src/data/references/modules/user/patterns.md b/src/data/references/modules/user/patterns.md index 37034d0..efe392e 100644 --- a/src/data/references/modules/user/patterns.md +++ b/src/data/references/modules/user/patterns.md @@ -1,5 +1,9 @@ # modules/user - Common Patterns +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). Helpers are +> invoked via `{% function %}`, never `{% include %}` — the LSP rejects the +> latter as `DeprecatedTag`. + ## Authentication Patterns ### Check if User is Logged In @@ -14,6 +18,7 @@ ### Conditional Content by Role ```liquid +{% graphql current_user = 'modules/user/queries/user/current' %} {% if current_user.roles contains 'admin' %}
      @@ -23,50 +28,71 @@ ## Authorization Patterns -### Require Authentication -Use the helper to redirect unauthenticated users: +Authorization helpers all take a `do:` parameter (the permission key) and a +`requester:` (the user profile). Always pull the user via the module query +first — never read `context.current_user` directly into the helper, because +the helper expects a profile shape, not the runtime context object. + +### Require Authentication (redirect if not authorized) ```liquid -{% include 'modules/user/helpers/can_do_or_redirect' - with_action: 'view_profile' -%} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, + do: 'profile.view', + return_url: '/sign-in' %}

      {{ current_user.first_name }}'s Profile

      ``` -### Check Permission Before Action +### Check Permission Before Showing UI ```liquid -{% include 'modules/user/helpers/can_do' with_action: 'edit_post' %} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function can = 'modules/user/helpers/can_do', + requester: current_user, + do: 'posts.edit' %} -{% if can_do %} +{% if can %} {% else %}

      You cannot edit this post

      {% endif %} ``` -### Admin-Only Pages +### Admin-Only Pages (404 / 403 if not authorized) ```liquid -{% include 'modules/user/helpers/can_do_or_unauthorized' - with_action: 'manage_users' -%} +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function _ = 'modules/user/helpers/can_do_or_unauthorized', + requester: current_user, + do: 'admin_pages.view', + redirect_anonymous_to_login: true %}

      User Management

      ``` +`can_do_or_unauthorized` returns 403 for authenticated users without the +permission; with `redirect_anonymous_to_login: true` it sends anonymous users +to `/sessions/new` and stashes the original URL in the session. + ## OAuth2 Patterns -### Social Login Button -```html - - Sign in with Google - +OAuth provider integrations live in the optional `oauth_github` module +(separate dependency since user 5.x). The `user` module exposes the OAuth +record CRUD; the actual sign-in flow is owned by the provider module. + +### Linked-providers query for the current user +```liquid +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function providers = 'modules/user/helpers/get_assigned_oauth_providers', + user_id: current_user.id %} +{% for p in providers %} + Linked: {{ p.provider }} ({{ p.sub }}) +{% endfor %} ``` -### Link Social Account +### Available providers (configured but not yet linked) ```liquid -{% graphql result = 'mutations/oauth/link_provider', - provider: 'github' -%} +{% function available = 'modules/user/helpers/get_available_oauth_providers', + user_id: current_user.id %} ``` ## User Data Patterns @@ -82,19 +108,22 @@ Use the helper to redirect unauthenticated users:
      ``` -### Update User Settings +### Update Profile via Module Command ```liquid -{% graphql %} - mutation UpdateSettings($bio: String) { - profile_update(data: { bio: $bio }) { - profile { id } - } - } -{% endgraphql %} +{% function result = 'modules/user/commands/profiles/update', + id: current_user.id, + first_name: 'Ada', + last_name: 'Lovelace' %} +{% if result.valid %} + Saved. +{% else %} + {{ result.errors }} +{% endif %} ``` ## See Also - configuration.md - Setup instructions -- api.md - API endpoints +- api.md - API surface overview - gotchas.md - Common mistakes -- advanced.md - Advanced techniques +- advanced.md - Advanced techniques (incl. permissions override + 2FA hooks) +- prerequisites.md - Required setup before using this module diff --git a/src/data/references/modules/user/prerequisites.md b/src/data/references/modules/user/prerequisites.md index 25342ee..5c3eb9d 100644 --- a/src/data/references/modules/user/prerequisites.md +++ b/src/data/references/modules/user/prerequisites.md @@ -1,93 +1,111 @@ # modules/user - Required Setup -## CRITICAL: Custom Permission Actions Require permissions.liquid +> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). All helper +> calls below use `{% function %}` and the `do:` parameter. The legacy +> `{% include %}` and `with_action:` forms are rejected by the LSP +> (`DeprecatedTag`) and must NOT be used. -If you use `can_do_or_redirect`, `can_do`, or `can_do_or_unauthorized` with **any custom action** -(i.e., anything other than built-in role names like `authenticated` or `admin`), you MUST create -this file first: +## CRITICAL: Custom Permission Actions Require an Override + +If you use `can_do_or_redirect`, `can_do`, or `can_do_or_unauthorized` with +ANY custom action string (anything beyond what the module's own pages need), +you MUST override the role-permissions query at: ``` -app/views/partials/permissions.liquid +app/modules/user/public/lib/queries/role_permissions/permissions.liquid ``` -**Without this file, all custom permission checks silently return false.** -This means `can_do_or_redirect` will redirect every user — including logged-in ones — back to the -home page, with no error message. This is the most common auth setup mistake. +**Without this override, every custom action denies every user — silently.** +There is no error: `can_do_or_redirect` simply sends the user away, +`can_do_or_unauthorized` returns 403, `can_do` returns false. This is the +single most common auth-setup mistake. -### Minimal permissions.liquid +### Minimal override -The file must handle the actions you define. Use `{% case action %}` to map actions to conditions: +The override must return a hash mapping role-name → list of action strings: ```liquid -{% case action %} - {% when 'blog_post.create' %} - {% if context.current_user %} - {% assign result = true %} - {% endif %} - - {% when 'blog_post.update' %} - {% if context.current_user.id == object.user_id %} - {% assign result = true %} - {% endif %} - - {% when 'blog_post.delete' %} - {% if context.current_user.id == object.user_id %} - {% assign result = true %} - {% endif %} -{% endcase %} +{% parse_json data %} +{ + "anonymous": ["sessions.create", "users.register"], + "authenticated": ["sessions.destroy", "oauth.manage"], + "member": ["profile.manage"], + "editor": ["posts.create", "posts.update"], + "admin": ["admin_pages.view", "admin.users.manage", "users.impersonate", "posts.create", "posts.update", "posts.delete"], + "superadmin": ["users.impersonate_superadmin"] +} +{% endparse_json %} + +{% return data %} ``` -The module checks `result`. If `result` is not `true`, the user is denied. +Every role you assign via `commands/profiles/roles/append` must appear as a +key. Every action you check via `can_do(do: '...')` must appear in at least +one role's list. ### "Any authenticated user" pattern -For actions that any logged-in user can perform: - ```liquid -{% case action %} - {% when 'blog_post.create' %} - {% if context.current_user %} - {% assign result = true %} - {% endif %} -{% endcase %} +{% parse_json data %} +{ + "authenticated": ["sessions.destroy", "posts.read", "comments.create"] +} +{% endparse_json %} +{% return data %} ``` -### Built-in role actions (no permissions.liquid needed) +Then: -These work without a custom permissions file because the module handles them internally: +```liquid +{% function _ = 'modules/user/helpers/can_do_or_redirect', + requester: current_user, + do: 'comments.create' %} +``` -- Checking `roles contains 'admin'` -- Using `with_action: 'authenticated'` (any logged-in user) +### Per-entity authorization (ownership, tenancy) -Only custom string actions like `'blog_post.create'` require the file. +Hash-only authorization can't express "user owns this row." Use an +`access_callback` (see advanced.md) — it receives `requester`, `entity`, +and `do`, and returns a boolean. The callback wins over the hash. --- -## IMPORTANT: include vs render for Auth Helpers +## CRITICAL: Use `{% function %}`, NOT `{% include %}` -Auth helpers (`can_do`, `can_do_or_redirect`, `can_do_or_unauthorized`) **must use `include`**, -not `render`. They need access to the caller's variable scope to set `can_do` and similar -variables that your template reads after the call. +The modernized canonical form for every helper call is `{% function %}`: ```liquid - -{% include 'modules/user/helpers/can_do' with_action: 'edit_post' %} -{% if can_do %} - + +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function can = 'modules/user/helpers/can_do', + requester: current_user, do: 'posts.edit' %} +{% if can %} + {% endif %} +``` - -{% render 'modules/user/helpers/can_do' with_action: 'edit_post' %} -{% if can_do %} -{% endif %} +```liquid + +{% include 'modules/user/helpers/can_do' with_action: 'posts.edit' %} ``` -The linter flags `include` as deprecated. **This warning is expected and unavoidable for auth helpers.** -The module API explicitly requires `include` for scope sharing. Use `include` and accept the warning. +`{% function %}` returns the helper's value into the named variable +(`can` above). `{% function _ = '...' %}` discards it when the helper is +side-effecting (redirect, 403). + +--- -Scaffold-generated auth checks use `{% function %}` (which calls commands/queries), so they do not -trigger this warning. The `include` requirement applies only when calling auth helpers directly from -your own partials or pages. +## CRITICAL: Always Pull `current_user` via the Module Query + +Helpers expect a profile-shaped `requester:` (with `id`, `roles`, etc.). +`context.current_user` is the runtime context object — different shape, not +interchangeable. ALWAYS: + +```liquid +{% graphql current_user = 'modules/user/queries/user/current' %} +{% function _ = 'modules/user/helpers/can_do', + requester: current_user, do: '...' %} +``` --- @@ -95,6 +113,22 @@ your own partials or pages. Before adding any auth checks to your pages or partials: -- [ ] `app/views/partials/permissions.liquid` exists and handles all custom actions you will use -- [ ] You know which actions require `include` (helpers) vs `{% function %}` (commands/queries) -- [ ] Pages that mutate data call the auth check **before** any command is executed +- [ ] `app/modules/user/public/lib/queries/role_permissions/permissions.liquid` exists and lists + EVERY role you assign + EVERY action you check +- [ ] All helper calls use `{% function %}` syntax (never `{% include %}`) +- [ ] All helper calls pass `requester:` from the module query, not from + `context.current_user` +- [ ] All helper calls use the `do:` parameter (never `with_action:`) +- [ ] Pages that mutate data call the auth helper BEFORE any + `commands/...` execution + +## Module Dependencies + +Per `modules/user/pos-module.json` (version 5.2.8): + +- `core` ≥ 2.1.8 (required) +- `common-styling` ≥ 1.11.0 (required) +- `oauth_github` ≥ 0.0.12 (optional — only if your app uses GitHub OAuth) + +Run `pos-cli modules version user` if `template-values.json` and +`pos-module.json` drift; the dashboard surfaces this via `manifest_warnings`. diff --git a/src/tools/analyze-project.js b/src/tools/analyze-project.js index 93b4a84..b72a873 100644 --- a/src/tools/analyze-project.js +++ b/src/tools/analyze-project.js @@ -510,19 +510,25 @@ function performIntegrityChecks(projectMap) { } // 3. Broken function calls (from pages, partials, commands, queries) - // In platformOS, {% function result = 'queries/X' %} resolves to app/lib/queries/X.liquid - // The lib/ prefix is implicit in function calls. + // In platformOS, both `{% function result = 'queries/X' %}` and + // `{% function result = 'lib/queries/X' %}` resolve to + // `app/lib/queries/X.liquid`. The `lib/` prefix is OPTIONAL, the `app/` + // prefix is implicit. Naively prepending `app/lib/` to a call that + // already carries `lib/` produces phantom `app/lib/lib/...` paths and + // false-positive missing_command/missing_query issues. const checkFunctionCalls = (sourcePath, functionCalls) => { for (const fc of functionCalls ?? []) { if (isModuleRef(fc.path)) continue; - // function call path → disk path: app/lib/{path}.liquid - const fullPath = `app/lib/${fc.path}.liquid`; - if (fc.path.includes('commands/') && !allCommands.has(fullPath)) { + // Strip optional leading `lib/` so `'lib/commands/X'` and `'commands/X'` + // both resolve to `app/lib/commands/X.liquid` consistently. + const stripped = fc.path.replace(/^lib\//, ''); + const fullPath = `app/lib/${stripped}.liquid`; + if (stripped.includes('commands/') && !allCommands.has(fullPath)) { issues.push({ type: 'missing_command', severity: 'error', source: sourcePath, target: fullPath, message: `'${sourcePath}' calls command '${fc.path}' (resolves to ${fullPath}) which does not exist`, }); - } else if (fc.path.includes('queries/') && !allQueries.has(fullPath)) { + } else if (stripped.includes('queries/') && !allQueries.has(fullPath)) { issues.push({ type: 'missing_query', severity: 'error', source: sourcePath, target: fullPath, message: `'${sourcePath}' calls query '${fc.path}' (resolves to ${fullPath}) which does not exist`, diff --git a/src/tools/module-info.js b/src/tools/module-info.js index fbb13b5..7fccf36 100644 --- a/src/tools/module-info.js +++ b/src/tools/module-info.js @@ -92,6 +92,8 @@ export const moduleInfoTool = { name, version: scan.version, dependencies: scan.dependencies, + ...(scan.manifest_source ? { manifest_source: scan.manifest_source } : {}), + ...(scan.manifest_warnings ? { manifest_warnings: scan.manifest_warnings } : {}), section: 'api', // Live scan is the source of truth — every entry includes call_syntax, // required_params, optional_params, and returns when the doc block @@ -114,6 +116,8 @@ export const moduleInfoTool = { name, version: scan.version, dependencies: scan.dependencies, + ...(scan.manifest_source ? { manifest_source: scan.manifest_source } : {}), + ...(scan.manifest_warnings ? { manifest_warnings: scan.manifest_warnings } : {}), section, reference: refDoc || `No ${section} documentation available for module '${name}'.`, // Include API surface for quick context @@ -169,6 +173,8 @@ async function buildOverview(name, scan) { display_name: scan.display_name, version: scan.version, dependencies: scan.dependencies, + ...(scan.manifest_source ? { manifest_source: scan.manifest_source } : {}), + ...(scan.manifest_warnings ? { manifest_warnings: scan.manifest_warnings } : {}), installed: true, // Required setup steps — always surfaced when docs exist so agents don't miss prerequisites diff --git a/src/tools/project-map.js b/src/tools/project-map.js index 03e87f3..2035093 100644 --- a/src/tools/project-map.js +++ b/src/tools/project-map.js @@ -16,6 +16,7 @@ export const projectMapTool = { Returns a structured JSON index of the platformOS project: schemas with property details, GraphQL operations with args, commands, queries, pages, partials with reverse-index, translations, and per-resource CRUD completeness. +You MUST run project_map with force_refresh: true after creating new commands, otherwise the LSP may has stale/cached state. MANDATE (NON-NEGOTIABLE): Call this tool ONCE at the very start of every session before using scaffold, validate_intent, diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js index 0b4cf11..a71293d 100644 --- a/src/tools/validate-code.js +++ b/src/tools/validate-code.js @@ -11,7 +11,7 @@ import { generateStructuralWarnings } from '../core/structural-warnings.js'; import { validateSchema } from '../core/schema-validator.js'; import { validateTranslationYaml } from '../core/translation-validator.js'; import { checkSchemaProperties } from '../core/schema-property-checker.js'; -import { runDiagnosticPipeline, stampDefaultsOn } from '../core/diagnostic-pipeline.js'; +import { runDiagnosticPipeline, stampDefaultsOn, suppressUpstreamFrontmatterDup } from '../core/diagnostic-pipeline.js'; import { isCheckForceDisabled } from '../core/rules/engine.js'; import { partitionCallersByPending } from '../core/pending-callers.js'; import { toUri, sanitizePath } from '../core/utils.js'; @@ -371,6 +371,15 @@ explicitly only if you are validating a file that is NOT part of the most recent } } + // 2c1. Drop upstream `ValidFrontmatter` rows that share a line with our + // richer `pos-supervisor:InvalidLayout` / `pos-supervisor:InvalidFrontMatter` + // diagnostics. pos-cli 6.0.7 ships `ValidFrontmatter` independently — + // without this dedup the agent sees two warnings for the same root + // cause (missing layout file, unknown frontmatter key). Upstream rows + // covering cases our checks don't handle (deprecated `layout_name`, + // missing required fields per file type) survive untouched. + suppressUpstreamFrontmatterDup(result); + // 2d. Diff-aware comparison — detect removed functionality on update (full mode) if (isLiquid && fileExists && result.structural && mode === 'full') { try { @@ -526,7 +535,43 @@ explicitly only if you are validating a file that is NOT part of the most recent ctx.directory, ); - result.proposed_fixes = proposedFixes; + // Precedence rule (2026-04-25): the rule engine is the source of + // truth for diagnostic-specific advice; the heuristic generator is + // the source of truth for actionable text_edits derived from + // AST/line position. When BOTH produce output for the same + // diagnostic, we merge them per-channel: + // + // - Heuristic `text_edit` → ALWAYS keep (actionable; complements + // any rule guidance). + // - Heuristic `guidance` → DROP if the rule already emitted any + // fix for this diagnostic. Otherwise + // keep (rule was silent → heuristic is + // the only signal). + // - Rule fixes → ALWAYS keep (priority-ordered; first + // match wins inside the rule engine). + // + // Without this gate, the agent saw competing guidance for the same + // root cause (rule's stale Levenshtein vs heuristic's specific-case + // detection), which actively misled fixes. See the 2026-04-25 + // TranslationKeyExists `[index]` regression report. + const rulesByDiag = new Map(); + for (const d of allDiagnostics) { + if (d.fixes?.length > 0) { + rulesByDiag.set(d, d.fixes); + } + } + // Build a Set of heuristic fix references owned by diagnostics that + // ALSO have rule fixes — those are the ones we'll filter to keep + // only text_edit (drop guidance). + const heuristicByDiagIdx = new Map(diagnosticFixes); // copy + const dropHeuristicGuidance = new Set(); + for (const [diagIdx, hFix] of heuristicByDiagIdx) { + const d = allDiagnostics[diagIdx]; + if (rulesByDiag.has(d) && hFix?.type === 'guidance') { + dropHeuristicGuidance.add(hFix); + } + } + result.proposed_fixes = proposedFixes.filter(f => !dropHeuristicGuidance.has(f)); // Merge rule-generated fixes into proposed_fixes for (const d of allDiagnostics) { @@ -542,13 +587,19 @@ explicitly only if you are validating a file that is NOT part of the most recent } } - // Attach per-diagnostic fix field - for (const [diagIdx, fix] of diagnosticFixes) { + // Attach per-diagnostic fix field — but if the rule won precedence + // and the heuristic was guidance-only, attach the rule's first fix + // instead so error.fix matches what proposed_fixes carries. + for (const [diagIdx, fix] of heuristicByDiagIdx) { const d = allDiagnostics[diagIdx]; + const ruleFixes = rulesByDiag.get(d); + const useFix = (ruleFixes && fix?.type === 'guidance') + ? { ...ruleFixes[0], source: 'rule', rule_id: d.rule_id ?? null } + : fix; if (d._origType === 'error') { - result.errors[d._origIdx].fix = fix; + result.errors[d._origIdx].fix = useFix; } else { - result.warnings[d._origIdx].fix = fix; + result.warnings[d._origIdx].fix = useFix; } } } catch (e) { diff --git a/tests/integration/analyze-project-lib-prefix.integration.test.js b/tests/integration/analyze-project-lib-prefix.integration.test.js new file mode 100644 index 0000000..6994b68 --- /dev/null +++ b/tests/integration/analyze-project-lib-prefix.integration.test.js @@ -0,0 +1,115 @@ +/** + * Regression test for the `app/lib/lib/...` phantom-path bug in + * analyze_project (2026-04-26). + * + * Cause: `src/tools/analyze-project.js` previously joined function-call + * paths as `app/lib/${fc.path}.liquid` without stripping an optional + * leading `lib/`. In platformOS, both `{% function = 'commands/X' %}` and + * `{% function = 'lib/commands/X' %}` are valid call forms — they both + * resolve to `app/lib/commands/X.liquid`. The naive join produced + * `app/lib/lib/commands/X.liquid` and then complained that the phantom + * file did not exist. + * + * Fix: `analyze-project.js` now strips the optional `lib/` prefix before + * joining, mirroring the resolution in `error-enricher.js` / + * `core/rules/queries.js` / `fix-generator.js` / + * `core/diagnostic-pipeline.js`. + */ + +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { writeFileSync, mkdirSync } from 'node:fs'; +import { join } from 'node:path'; +import { startServer, FIXTURE_DIR, createTempProject } from './helpers/server.js'; + +setDefaultTimeout(60_000); + +let server; +let proj; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + + // Create a real command + a build phase that the page calls under both + // call-form shapes. Both should resolve to the SAME file on disk. + const cmdDir = join(proj.dir, 'app/lib/commands/contacts/create'); + mkdirSync(cmdDir, { recursive: true }); + writeFileSync( + join(proj.dir, 'app/lib/commands/contacts/create.liquid'), + [ + '{% doc %}', + ' @param object {object} - input contact', + '{% enddoc %}', + '{% liquid', + " function object = 'commands/contacts/create/build', object: object", + " function object = 'lib/commands/contacts/create/build', object: object", + ' return object', + '%}', + '', + ].join('\n'), + 'utf8', + ); + writeFileSync( + join(cmdDir, 'build.liquid'), + "{% doc %}\n @param object {object}\n{% enddoc %}\n{% return object %}\n", + 'utf8', + ); + + // Page that calls a command which DOES NOT exist on disk — exercises the + // false-negative guard (genuine miss must still be flagged). + mkdirSync(join(proj.dir, 'app/views/pages/contacts'), { recursive: true }); + writeFileSync( + join(proj.dir, 'app/views/pages/contacts/test_miss.html.liquid'), + [ + '---', + 'slug: contacts/test-miss', + '---', + '{% liquid', + " function r = 'commands/contacts/never_written', object: context.params", + '%}', + '', + ].join('\n'), + 'utf8', + ); + + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +describe("analyze_project — function-call resolution doesn't double the lib/ prefix", () => { + it('does NOT emit missing_command for `lib/commands/X` when the file exists at app/lib/commands/X.liquid', async () => { + const result = await server.callTool('analyze_project', {}); + const phantom = result.integrity.filter(i => + i.type === 'missing_command' && + // Phantom path would carry double `lib/lib/`. + (/app\/lib\/lib\//.test(i.target ?? '') || /app\/lib\/lib\//.test(i.message ?? '')) + ); + if (phantom.length > 0) { + console.log('Phantom missing_command issues:', phantom); + } + expect(phantom).toHaveLength(0); + }); + + it('also does not flag the bare `commands/X` form when the file exists', async () => { + const result = await server.callTool('analyze_project', {}); + const flagged = result.integrity.filter(i => + i.type === 'missing_command' && + (i.message ?? '').includes("'commands/contacts/create/build'") + ); + expect(flagged).toHaveLength(0); + }); + + it('still flags genuinely missing commands (no false negative)', async () => { + const result = await server.callTool('analyze_project', {}); + const miss = result.integrity.filter(i => + i.type === 'missing_command' && + (i.message ?? '').includes('commands/contacts/never_written') + ); + expect(miss.length).toBeGreaterThan(0); + // The reported target path uses the canonical resolution (single lib/). + expect(miss[0].target).toBe('app/lib/commands/contacts/never_written.liquid'); + }); +}); diff --git a/tests/integration/pos-cli/translation-array-index.test.js b/tests/integration/pos-cli/translation-array-index.test.js new file mode 100644 index 0000000..c2b3bd9 --- /dev/null +++ b/tests/integration/pos-cli/translation-array-index.test.js @@ -0,0 +1,102 @@ +/** + * Regression test for the fix-channel duplication bug (2026-04-25). + * + * Before this fix, an indexed translation key like `key[0]` produced THREE + * proposed_fixes per error: + * 1. A correct heuristic guidance ("Pass the full array, then iterate…"). + * 2. The rule engine's stale `suggest_nearest` guidance ("Replace with + * `en.parent.items`…") — Levenshtein found the parent key as the + * closest match, which is misleading. + * 3. Same as #2 for the second error. + * + * The fix: + * - The array-index case is now owned by a dedicated rule + * `TranslationKeyExists.array_index_misuse` (priority 5). + * - `suggest_nearest` and `create_key` are gated to NOT fire on indexed + * keys. + * - The validate-code merge loop drops heuristic GUIDANCE when a rule + * fix exists for the same diagnostic; heuristic TEXT_EDIT survives + * (actionable diff complements rule narrative). + * + * This test drives the full pipeline (validate_code, full mode) and + * asserts the agent sees ONLY the iteration guidance per error, not + * the misleading nearest-key suggestion. + */ + +import { it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { describePosCli } from './guard.js'; +import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js'; + +setDefaultTimeout(30_000); + +let server; +let proj; + +beforeAll(async () => { + proj = createTempProject(FIXTURE_DIR); + server = await startServer(proj.dir); +}); + +afterAll(() => { + server?.stop(); + proj?.cleanup(); +}); + +// Using a key whose namespace exists in the fixture so the LSP actually +// fires `TranslationKeyExists`. `blog_posts.titl[0]` is close enough to the +// fixture's `blog_posts.title` that the parent key would have been the +// nearest-match candidate before the fix. Path is a flat partial — LSP +// translation resolution is path-sensitive in the fixture project, and +// nested subdirs sometimes skip the check. +const FILE = 'app/views/partials/test_arr.liquid'; +const CONTENT = "{{ 'blog_posts.titl[0]' | t }}"; + +describePosCli('translation array-index misuse: single-source-of-truth fix', () => { + it('emits ONE iteration guidance per error, never the misleading "nearest key" suggestion', async () => { + const result = await server.callTool('validate_code', { + file_path: FILE, + content: CONTENT, + mode: 'full', + }); + + const tkeDiags = [ + ...result.errors.filter(e => e.check === 'TranslationKeyExists'), + ...result.warnings.filter(w => w.check === 'TranslationKeyExists'), + ]; + expect(tkeDiags.length).toBeGreaterThanOrEqual(1); + + // Each diagnostic carries the array-index rule attribution. + for (const d of tkeDiags) { + expect(d.rule_id).toBe('TranslationKeyExists.array_index_misuse'); + } + + // Filter proposed_fixes to ones from these TranslationKeyExists rows. + const tkeProposed = result.proposed_fixes.filter(f => + f.check === 'TranslationKeyExists' || /TranslationKeyExists/.test(f.rule_id ?? '') + ); + expect(tkeProposed.length).toBeGreaterThan(0); + + for (const f of tkeProposed) { + // Modern attribution wins for both rule and (any surviving) heuristic. + const id = f.rule_id ?? ''; + const isArrayRule = id === 'TranslationKeyExists.array_index_misuse'; + const isStrippedHeuristic = id.startsWith('heuristic:TranslationKeyExists'); + expect(isArrayRule || isStrippedHeuristic).toBe(true); + + // No fix should suggest the misleading "did you mean" or + // "Replace 'foo[0]' with 'foo'" rewrite. The bug we're guarding + // against was: the rule's stale `suggest_nearest` proposing the + // parent key as a "did you mean" candidate. + expect(f.description).not.toMatch(/[Dd]id you mean/); + expect(f.description).not.toMatch(/Replace `blog_posts\.titl\[\d+\]` with `blog_posts/); + } + + // Spot-check the iteration-guidance shape on at least one fix. + const arrayFix = tkeProposed.find(f => f.rule_id === 'TranslationKeyExists.array_index_misuse'); + expect(arrayFix).toBeDefined(); + expect(arrayFix.description).toMatch(/\{% for item in items %\}/); + expect(arrayFix.description).toMatch(/blog_posts\.titl/); + // arrayKey reference must NOT carry the [0]/[1] suffix. + expect(arrayFix.description).not.toMatch(/blog_posts\.titl\[\d+\]/); + }); +}); diff --git a/tests/integration/project-map.integration.test.js b/tests/integration/project-map.integration.test.js index 9d8f4d6..604e7d2 100644 --- a/tests/integration/project-map.integration.test.js +++ b/tests/integration/project-map.integration.test.js @@ -98,7 +98,7 @@ describe('project_map — full scope', () => { const result = await server.callTool('project_map', { scope: 'full' }); expect(result.summary.file_counts.schema).toBe(1); expect(result.summary.file_counts.graphql).toBe(4); - expect(result.summary.file_counts.pages).toBe(2); + expect(result.summary.file_counts.pages).toBe(3); expect(result.summary.file_counts.assets).toBeGreaterThan(0); }); diff --git a/tests/unit/diagnostic-pipeline-frontmatter-dedup.test.js b/tests/unit/diagnostic-pipeline-frontmatter-dedup.test.js new file mode 100644 index 0000000..08b6ae2 --- /dev/null +++ b/tests/unit/diagnostic-pipeline-frontmatter-dedup.test.js @@ -0,0 +1,171 @@ +/** + * Suppression of upstream `ValidFrontmatter` rows that overlap with our + * richer `pos-supervisor:InvalidLayout` / `pos-supervisor:InvalidFrontMatter` + * structural checks (pos-cli 6.0.7 alignment, 2026-04-25). + * + * Line-anchored: YAML frontmatter is one key per line, so a line collision + * is a reliable signal of the same root cause. + */ + +import { describe, it, expect } from 'bun:test'; +import { suppressUpstreamFrontmatterDup } from '../../src/core/diagnostic-pipeline.js'; + +function makeResult({ errors = [], warnings = [], infos = [] } = {}) { + return { errors: [...errors], warnings: [...warnings], infos: [...infos] }; +} + +describe('suppressUpstreamFrontmatterDup', () => { + it('drops ValidFrontmatter when pos-supervisor:InvalidLayout shares its line', () => { + const result = makeResult({ + warnings: [ + { + check: 'ValidFrontmatter', + severity: 'warning', + message: "Layout 'nonexistent_layout_xyz' does not exist", + line: 3, + }, + { + check: 'pos-supervisor:InvalidLayout', + severity: 'warning', + message: 'Layout `nonexistent_layout_xyz` not found. Expected file: …', + line: 3, + }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(1); + expect(result.warnings).toHaveLength(1); + expect(result.warnings[0].check).toBe('pos-supervisor:InvalidLayout'); + expect(result.infos.some(i => i.check === 'pos-supervisor:DuplicateFrontmatterCheck')).toBe(true); + }); + + it('drops ValidFrontmatter when pos-supervisor:InvalidFrontMatter shares its line (error severity)', () => { + const result = makeResult({ + errors: [ + { + check: 'pos-supervisor:InvalidFrontMatter', + severity: 'error', + message: '`cache` is not a front matter option. Use `{% cache key, expire: 3600 %}`.', + line: 3, + }, + ], + warnings: [ + { + check: 'ValidFrontmatter', + severity: 'warning', + message: "Unknown frontmatter field 'cache' in Page file", + line: 3, + }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(1); + expect(result.errors).toHaveLength(1); + expect(result.warnings).toHaveLength(0); + }); + + it('keeps ValidFrontmatter rows that do NOT overlap with our checks', () => { + // Upstream catches deprecated `layout_name` — we don't have a structural + // check for this, so the warning should survive untouched. + const result = makeResult({ + warnings: [ + { + check: 'ValidFrontmatter', + severity: 'warning', + message: "Use 'layout' instead of deprecated 'layout_name'", + line: 4, + }, + { + check: 'pos-supervisor:InvalidLayout', + severity: 'warning', + message: 'Layout `application` not found.', + line: 2, + }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(0); + expect(result.warnings).toHaveLength(2); + expect(result.infos).toHaveLength(0); + }); + + it('is a no-op when no pos-supervisor structural check is present', () => { + const result = makeResult({ + warnings: [ + { + check: 'ValidFrontmatter', + severity: 'warning', + message: "Layout 'foo' does not exist", + line: 3, + }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(0); + expect(result.warnings).toHaveLength(1); + expect(result.infos).toHaveLength(0); + }); + + it('is a no-op when no ValidFrontmatter row is present', () => { + const result = makeResult({ + warnings: [ + { + check: 'pos-supervisor:InvalidLayout', + severity: 'warning', + message: 'Layout `application` not found.', + line: 3, + }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(0); + expect(result.warnings).toHaveLength(1); + expect(result.infos).toHaveLength(0); + }); + + it('idempotent — second call after dedup is a no-op', () => { + const result = makeResult({ + warnings: [ + { check: 'ValidFrontmatter', severity: 'warning', message: 'x', line: 3 }, + { check: 'pos-supervisor:InvalidLayout', severity: 'warning', message: 'y', line: 3 }, + ], + }); + + expect(suppressUpstreamFrontmatterDup(result)).toBe(1); + expect(suppressUpstreamFrontmatterDup(result)).toBe(0); + expect(result.warnings).toHaveLength(1); + // Only one info note was added — no duplicate from the second call. + expect(result.infos.filter(i => i.check === 'pos-supervisor:DuplicateFrontmatterCheck')) + .toHaveLength(1); + }); + + it('drops both ValidFrontmatter rows when multiple of our checks fire', () => { + const result = makeResult({ + errors: [ + { check: 'pos-supervisor:InvalidFrontMatter', severity: 'error', message: 'a', line: 3 }, + ], + warnings: [ + { check: 'pos-supervisor:InvalidLayout', severity: 'warning', message: 'b', line: 4 }, + { check: 'ValidFrontmatter', severity: 'warning', message: 'a-upstream', line: 3 }, + { check: 'ValidFrontmatter', severity: 'warning', message: 'b-upstream', line: 4 }, + { check: 'ValidFrontmatter', severity: 'warning', message: 'novel-upstream', line: 5 }, + ], + }); + + const removed = suppressUpstreamFrontmatterDup(result); + + expect(removed).toBe(2); + // The line-5 ValidFrontmatter is novel and survives. + expect(result.warnings.find(w => w.check === 'ValidFrontmatter').line).toBe(5); + }); +}); diff --git a/tests/unit/module-scanner-manifest.test.js b/tests/unit/module-scanner-manifest.test.js new file mode 100644 index 0000000..ee2a844 --- /dev/null +++ b/tests/unit/module-scanner-manifest.test.js @@ -0,0 +1,233 @@ +/** + * Module-scanner manifest precedence + drift detection (Phase 4 of the + * pos-cli 6.0.7 alignment plan, 2026-04-25). + * + * Senior-dev contract: `pos-module.json` is the upstream platformOS + * authoritative manifest. `template-values.json` is a generated mirror that + * can drift if module deps are added without re-running `pos-cli modules + * version`. `package.json` is npm metadata — its `version` is unrelated to + * the platformOS module version. The scanner must reflect this hierarchy. + * + * These tests run with throwaway fixtures so they cannot interfere with the + * shared module-scanner.test.js fixture (which only ships template-values.json). + */ + +import { describe, it, expect, beforeEach, afterEach } from 'bun:test'; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; + +import { scanModule, listModules } from '../../src/core/module-scanner.js'; + +let projectDir; + +beforeEach(() => { + projectDir = mkdtempSync(join(tmpdir(), 'module-scanner-manifest-')); +}); + +afterEach(() => { + try { rmSync(projectDir, { recursive: true, force: true }); } catch {} +}); + +function write(relPath, content) { + const abs = join(projectDir, relPath); + mkdirSync(join(abs, '..'), { recursive: true }); + writeFileSync(abs, content, 'utf8'); +} + +describe('module-scanner: manifest precedence', () => { + it('pos-module.json wins over template-values.json when both exist', async () => { + write('modules/user/pos-module.json', JSON.stringify({ + machine_name: 'user', + name: 'User', + version: '5.2.8', + dependencies: { core: '^2.1.8', 'common-styling': '^1.11.0', oauth_github: '^0.0.12' }, + })); + write('modules/user/template-values.json', JSON.stringify({ + name: 'User (template-values)', + machine_name: 'user', + type: 'module', + version: '5.2.8', + dependencies: { core: '^2.1.8', 'common-styling': '^1.11.0' }, // missing oauth_github + })); + write('modules/user/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'user'); + + expect(scan.version).toBe('5.2.8'); + // Authoritative dependency list comes from pos-module.json (3 entries). + expect(scan.dependencies.oauth_github).toBe('^0.0.12'); + expect(Object.keys(scan.dependencies)).toHaveLength(3); + expect(scan.manifest_source).toBe('pos-module.json'); + // Display name comes from pos-module.json's `name`, not template-values. + expect(scan.display_name).toBe('User'); + }); + + it('falls back to template-values.json when pos-module.json is absent', async () => { + write('modules/legacy/template-values.json', JSON.stringify({ + name: 'Legacy', + machine_name: 'legacy', + type: 'module', + version: '0.9.0', + dependencies: { core: '^1.0.0' }, + })); + write('modules/legacy/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'legacy'); + + expect(scan.version).toBe('0.9.0'); + expect(scan.dependencies.core).toBe('^1.0.0'); + expect(scan.manifest_source).toBe('template-values.json'); + expect(scan.manifest_warnings).toBeUndefined(); + }); + + it('falls back to package.json when neither platformOS manifest exists', async () => { + write('modules/npm-only/package.json', JSON.stringify({ + name: 'pos-module-npm-only', + version: '3.1.4', + dependencies: { foo: '^1.0.0' }, + })); + write('modules/npm-only/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'npm-only'); + + expect(scan.version).toBe('3.1.4'); + expect(scan.dependencies.foo).toBe('^1.0.0'); + expect(scan.manifest_source).toBe('package.json'); + }); + + it('returns sentinel manifest_source: null when no manifest is present', async () => { + write('modules/bare/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'bare'); + + expect(scan.version).toBe('unknown'); + expect(scan.dependencies).toEqual({}); + expect(scan.manifest_source).toBeNull(); + }); + + it('listModules surfaces manifest_source for every module', async () => { + write('modules/a/pos-module.json', JSON.stringify({ name: 'A', version: '1.0.0', dependencies: {} })); + write('modules/b/template-values.json', JSON.stringify({ name: 'B', version: '2.0.0', dependencies: {} })); + write('modules/c/package.json', JSON.stringify({ name: 'C', version: '3.0.0' })); + + const list = await listModules(projectDir); + const byName = Object.fromEntries(list.map(m => [m.name, m.manifest_source])); + + expect(byName.a).toBe('pos-module.json'); + expect(byName.b).toBe('template-values.json'); + expect(byName.c).toBe('package.json'); + }); + + it('malformed pos-module.json falls through to template-values.json', async () => { + write('modules/broken/pos-module.json', '{ not valid json'); + write('modules/broken/template-values.json', JSON.stringify({ + name: 'Broken', + version: '1.0.0', + dependencies: {}, + })); + write('modules/broken/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'broken'); + + expect(scan.version).toBe('1.0.0'); + expect(scan.manifest_source).toBe('template-values.json'); + }); +}); + +describe('module-scanner: manifest drift detection', () => { + it('flags dependency_drift when pos-module.json adds deps missing from template-values.json', async () => { + write('modules/user/pos-module.json', JSON.stringify({ + name: 'User', + version: '5.2.8', + dependencies: { core: '^2.1.8', 'common-styling': '^1.11.0', oauth_github: '^0.0.12' }, + })); + write('modules/user/template-values.json', JSON.stringify({ + name: 'User', + version: '5.2.8', + dependencies: { core: '^2.1.8', 'common-styling': '^1.11.0' }, + })); + write('modules/user/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'user'); + expect(Array.isArray(scan.manifest_warnings)).toBe(true); + const drift = scan.manifest_warnings.find(w => w.kind === 'dependency_drift'); + expect(drift).toBeDefined(); + expect(drift.only_in_pos_module).toEqual(['oauth_github']); + expect(drift.only_in_template_values).toEqual([]); + expect(drift.message).toMatch(/oauth_github/); + expect(drift.message).toMatch(/pos-cli modules version/); + }); + + it('flags drift in the other direction (template-values has extra deps)', async () => { + write('modules/x/pos-module.json', JSON.stringify({ + name: 'X', + version: '1.0.0', + dependencies: { core: '^1.0.0' }, + })); + write('modules/x/template-values.json', JSON.stringify({ + name: 'X', + version: '1.0.0', + dependencies: { core: '^1.0.0', stray: '^9.9.9' }, + })); + write('modules/x/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'x'); + const drift = scan.manifest_warnings.find(w => w.kind === 'dependency_drift'); + expect(drift.only_in_template_values).toEqual(['stray']); + expect(drift.only_in_pos_module).toEqual([]); + }); + + it('flags version_drift when the two files report different versions', async () => { + write('modules/x/pos-module.json', JSON.stringify({ + name: 'X', + version: '2.0.0', + dependencies: {}, + })); + write('modules/x/template-values.json', JSON.stringify({ + name: 'X', + version: '1.0.0', + dependencies: {}, + })); + write('modules/x/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'x'); + const v = scan.manifest_warnings.find(w => w.kind === 'version_drift'); + expect(v).toBeDefined(); + expect(v.pos_module).toBe('2.0.0'); + expect(v.template_values).toBe('1.0.0'); + // Authoritative version is pos-module.json's. + expect(scan.version).toBe('2.0.0'); + }); + + it('does NOT emit manifest_warnings when both manifests agree', async () => { + write('modules/x/pos-module.json', JSON.stringify({ + name: 'X', + version: '1.0.0', + dependencies: { core: '^1.0.0' }, + })); + write('modules/x/template-values.json', JSON.stringify({ + name: 'X', + version: '1.0.0', + dependencies: { core: '^1.0.0' }, + })); + write('modules/x/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'x'); + expect(scan.manifest_warnings).toBeUndefined(); + }); + + it('does NOT emit manifest_warnings when only one manifest exists', async () => { + // Only pos-module.json — no peer to compare against. + write('modules/a/pos-module.json', JSON.stringify({ + name: 'A', + version: '1.0.0', + dependencies: { core: '^1.0.0' }, + })); + write('modules/a/public/lib/helpers/noop.liquid', '{% return null %}'); + + const scan = await scanModule(projectDir, 'a'); + expect(scan.manifest_warnings).toBeUndefined(); + expect(scan.manifest_source).toBe('pos-module.json'); + }); +}); diff --git a/tests/unit/rules/DuplicateFunctionArguments.test.js b/tests/unit/rules/DuplicateFunctionArguments.test.js new file mode 100644 index 0000000..2557d0d --- /dev/null +++ b/tests/unit/rules/DuplicateFunctionArguments.test.js @@ -0,0 +1,38 @@ +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js'; +import { rules } from '../../../src/core/rules/DuplicateFunctionArguments.js'; + +beforeEach(() => { clearRules(); registerRules(rules); }); +afterEach(() => { clearRules(); }); + +function diag(extra = {}) { + return { + check: 'DuplicateFunctionArguments', + params: { argument: 'foo', tag_kind: 'function', partial: 'helpers/can_do', ...extra }, + message: '', + }; +} + +describe('DuplicateFunctionArguments.default', () => { + test('attribution + hint name the argument and partial for function tag', () => { + const r = runRules(diag(), {}); + expect(r.rule_id).toBe('DuplicateFunctionArguments.default'); + expect(r.hint_md).toMatch(/`foo`/); + expect(r.hint_md).toMatch(/helpers\/can_do/); + expect(r.hint_md).toMatch(/\{% function/); + expect(r.confidence).toBe(0.9); + }); + + test('render variant surfaces the right tag in the hint', () => { + const r = runRules(diag({ tag_kind: 'render', partial: 'forms/login', argument: 'email' }), {}); + expect(r.hint_md).toMatch(/`email`/); + expect(r.hint_md).toMatch(/\{% render/); + expect(r.hint_md).toMatch(/forms\/login/); + }); + + test('falls back to safe wording when params are missing', () => { + const r = runRules({ check: 'DuplicateFunctionArguments', message: '' }, {}); + expect(r.rule_id).toBe('DuplicateFunctionArguments.default'); + expect(r.hint_md).toMatch(/duplicate argument/i); + }); +}); diff --git a/tests/unit/rules/JsonLiteralQuoteStyle.test.js b/tests/unit/rules/JsonLiteralQuoteStyle.test.js new file mode 100644 index 0000000..4bab886 --- /dev/null +++ b/tests/unit/rules/JsonLiteralQuoteStyle.test.js @@ -0,0 +1,16 @@ +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js'; +import { rules } from '../../../src/core/rules/JsonLiteralQuoteStyle.js'; + +beforeEach(() => { clearRules(); registerRules(rules); }); +afterEach(() => { clearRules(); }); + +describe('JsonLiteralQuoteStyle.default', () => { + test('attributes every emit (single-shot rule)', () => { + const r = runRules({ check: 'JsonLiteralQuoteStyle', params: {}, message: '' }, {}); + expect(r.rule_id).toBe('JsonLiteralQuoteStyle.default'); + expect(r.hint_md).toMatch(/double-quoted/); + expect(r.hint_md).toMatch(/JSON literal/); + expect(r.confidence).toBe(0.95); + }); +}); diff --git a/tests/unit/rules/TranslationKeyExists.test.js b/tests/unit/rules/TranslationKeyExists.test.js index f2198e1..4c8429b 100644 --- a/tests/unit/rules/TranslationKeyExists.test.js +++ b/tests/unit/rules/TranslationKeyExists.test.js @@ -46,6 +46,72 @@ describe('TranslationKeyExists.create_key', () => { }); }); +describe('TranslationKeyExists.array_index_misuse', () => { + test('fires on `key[0]` and provides iteration guidance instead of nearest', () => { + const diag = { + check: 'TranslationKeyExists', + params: { key: 'landing.problem.items[0]' }, + }; + const result = runRules(diag, facts); + expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse'); + // Hint references the canonical iteration pattern, NOT a "did you mean" suggestion. + expect(result.hint_md).toMatch(/assign items/); + expect(result.hint_md).toMatch(/landing\.problem\.items/); + // The arrayKey reference must NOT carry the [0] suffix. + expect(result.hint_md).not.toMatch(/landing\.problem\.items\[0\]['"]\s*\| t/); + expect(result.fixes).toHaveLength(1); + expect(result.fixes[0].type).toBe('guidance'); + expect(result.fixes[0].description).toMatch(/\{% for item in items %\}/); + expect(result.confidence).toBe(0.9); + }); + + test('also catches multi-segment indices (`items[12]`)', () => { + const diag = { + check: 'TranslationKeyExists', + params: { key: 'landing.problem.items[12]' }, + }; + const result = runRules(diag, facts); + expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse'); + }); + + test('suggest_nearest does NOT fire for indexed keys (would be misleading)', () => { + // Even with a Levenshtein-close parent key in the graph, the array-index + // rule wins by priority. The suggest_nearest path is gated by an explicit + // check so it never produces "did you mean en.parent.items". + const indexedFacts = { + graph: buildFactGraph({ + pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, + translations: { en: { 'landing.problem.items': ['a', 'b'] } }, + assets: [], + }), + }; + const diag = { + check: 'TranslationKeyExists', + params: { key: 'landing.problem.items[0]' }, + }; + const result = runRules(diag, indexedFacts); + expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse'); + expect(result.rule_id).not.toBe('TranslationKeyExists.suggest_nearest'); + }); + + test('create_key does NOT fire for indexed keys (would propose nonsense YAML)', () => { + // Empty translations graph forces create_key to be the only otherwise-eligible rule. + // Array-index rule must still win. + const emptyFacts = { + graph: buildFactGraph({ + pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, + translations: {}, assets: [], + }), + }; + const diag = { + check: 'TranslationKeyExists', + params: { key: 'landing.problem.items[0]' }, + }; + const result = runRules(diag, emptyFacts); + expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse'); + }); +}); + describe('TranslationKeyExists — edge cases', () => { test('returns null when key param is missing', () => { const diag = { check: 'TranslationKeyExists', params: {} }; diff --git a/tests/unit/rules/ValidFrontmatter.test.js b/tests/unit/rules/ValidFrontmatter.test.js new file mode 100644 index 0000000..969ba81 --- /dev/null +++ b/tests/unit/rules/ValidFrontmatter.test.js @@ -0,0 +1,141 @@ +/** + * ValidFrontmatter rule attribution + hint routing per category. + * + * Each category in the rule module dispatches on `diag.params.category` + * (set by the EXTRACTOR in core/diagnostic-record.js). These tests pin: + * - The right rule fires for each category. + * - Hint content surfaces the field/file_type/value the agent needs. + * - The fallback rule covers the unknown shape so every emit is attributed. + */ + +import { describe, test, expect, beforeEach, afterEach } from 'bun:test'; +import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js'; +import { rules } from '../../../src/core/rules/ValidFrontmatter.js'; + +const facts = {}; // Frontmatter rules don't depend on fact graph. + +beforeEach(() => { clearRules(); registerRules(rules); }); +afterEach(() => { clearRules(); }); + +function diag(category, extra = {}) { + return { + check: 'ValidFrontmatter', + params: { category, ...extra }, + message: '', + file: 'app/views/pages/x.liquid', + line: 3, + column: 0, + }; +} + +describe('ValidFrontmatter.home_deprecated', () => { + test('attributes home-rename diagnostics', () => { + const r = runRules(diag('home_deprecated'), facts); + expect(r.rule_id).toBe('ValidFrontmatter.home_deprecated'); + expect(r.hint_md).toMatch(/index\.html\.liquid/); + expect(r.confidence).toBe(0.85); + }); +}); + +describe('ValidFrontmatter.missing_required', () => { + test('names the required field and file type in the hint', () => { + const r = runRules(diag('missing_required', { field: 'name', file_type: 'Form' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.missing_required'); + expect(r.hint_md).toMatch(/`name`/); + expect(r.hint_md).toMatch(/Form/); + expect(r.see_also?.tool).toBe('domain_guide'); + }); + + test('falls back gracefully when file_type is unknown', () => { + const r = runRules(diag('missing_required', { field: 'method' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.missing_required'); + expect(r.hint_md).toMatch(/`method`/); + }); +}); + +describe('ValidFrontmatter.unknown_field', () => { + test('names the offending key', () => { + const r = runRules(diag('unknown_field', { field: 'cache', file_type: 'Page' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.unknown_field'); + expect(r.hint_md).toMatch(/`cache`/); + }); +}); + +describe('ValidFrontmatter.deprecated_field', () => { + test('names the deprecated key', () => { + const r = runRules(diag('deprecated_field', { field: 'layout_name' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.deprecated_field'); + expect(r.hint_md).toMatch(/`layout_name`/); + }); +}); + +describe('ValidFrontmatter.invalid_enum', () => { + test('uppercase HTTP method gets case-canonicalisation guidance', () => { + const r = runRules(diag('invalid_enum', { + field: 'method', + value: 'POST', + allowed: 'get, post, put, delete, patch', + }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.invalid_enum'); + // Canonical-case suggestion ('post') surfaces in the hint. + expect(r.hint_md).toMatch(/`post`/); + }); + + test('truly out-of-range value gets allowed-list guidance', () => { + const r = runRules(diag('invalid_enum', { + field: 'method', + value: 'connect', + allowed: 'get, post, put, delete, patch', + }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.invalid_enum'); + expect(r.hint_md).toMatch(/get, post, put, delete, patch/); + }); +}); + +describe('ValidFrontmatter.layout_false', () => { + test('explains the YAML-boolean footgun', () => { + const r = runRules(diag('layout_false'), facts); + expect(r.rule_id).toBe('ValidFrontmatter.layout_false'); + expect(r.hint_md).toMatch(/`layout: ''`/); + expect(r.confidence).toBe(0.9); + }); +}); + +describe('ValidFrontmatter.layout_missing', () => { + test('app-level layout produces the canonical expected path', () => { + const r = runRules(diag('layout_missing', { layout: 'application' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.layout_missing'); + expect(r.hint_md).toMatch(/app\/views\/layouts\/application\./); + }); + + test('module-prefixed layout produces the module expected path', () => { + const r = runRules(diag('layout_missing', { layout: 'modules/core/admin' }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.layout_missing'); + expect(r.hint_md).toMatch(/modules\/core\/public\/views\/layouts\/admin\./); + }); +}); + +describe('ValidFrontmatter.association_missing', () => { + test('preserves the upstream label', () => { + const r = runRules(diag('association_missing', { + label: 'Authorization policy', + name: 'guest_only', + }), facts); + expect(r.rule_id).toBe('ValidFrontmatter.association_missing'); + expect(r.hint_md).toMatch(/Authorization policy/); + expect(r.hint_md).toMatch(/`guest_only`/); + }); +}); + +describe('ValidFrontmatter.fallback', () => { + test('attributes unknown shapes (so analytics never see .unmatched)', () => { + const r = runRules(diag('unknown'), facts); + expect(r.rule_id).toBe('ValidFrontmatter.fallback'); + expect(r.confidence).toBe(0.5); + }); + + test('also catches diagnostics with no params at all', () => { + const r = runRules({ check: 'ValidFrontmatter', message: 'mystery message' }, facts); + expect(r.rule_id).toBe('ValidFrontmatter.fallback'); + }); +}); diff --git a/tests/upstream/assign-syntax-coverage.test.js b/tests/upstream/assign-syntax-coverage.test.js new file mode 100644 index 0000000..c2cc023 --- /dev/null +++ b/tests/upstream/assign-syntax-coverage.test.js @@ -0,0 +1,116 @@ +/** + * Coverage probe for `InvalidAssignSyntax` and `InvalidOutputPush` — + * the assign/push grammar checks described in `docs/upstream-changes/ + * upstream-changes.md` sections A and C. + * + * Status as of pos-cli 6.0.7: these checks live in the parser-side repo + * but have NOT been shipped in `@platformos/platformos-check-common` yet. + * The parser dependency was bumped to ^0.0.17 in Phase 6 (the grammar + * change is in the parser); the LSP-level checks land separately. + * + * This file is a deferred coverage probe. It runs every CI cycle and + * LOGS whether the LSP now reports `InvalidAssignSyntax` / + * `InvalidOutputPush` for the canonical trigger inputs. It does NOT + * fail when the checks are absent — that's the current expected state. + * + * When the checks DO ship in a future pos-cli, the test surfaces it via + * the [SHIPPED] log line. At that point we should: + * 1. Add hint files (`src/data/hints/InvalidAssignSyntax.md`, + * `src/data/hints/InvalidOutputPush.md`). + * 2. Add rule modules (`src/core/rules/InvalidAssignSyntax.js`, + * `src/core/rules/InvalidOutputPush.js`) with priority-ordered + * categories, mirroring the Phase 3 ValidFrontmatter / JsonLiteralQuoteStyle + * treatment. + * 3. Add fingerprint pins in `tests/upstream/diagnostic-fingerprint.test.js`. + * 4. Replace the loose `expect(true).toBe(true)` with hard assertions on + * the emitted diagnostic shape (mirroring lsp-coverage-map.test.js). + * 5. Update `docs/upstream-changes/upstream-changes.md` to mark sections + * A and C as ABSORBED (currently OBSERVED-ONLY). + * + * The triggers below come straight from upstream PR-A and PR-C test cases + * so when the checks ship we'll already be aligned with their canonical + * inputs. + */ +import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test'; +import { describePosCli } from '../integration/pos-cli/guard.js'; +import { startServer, FIXTURE_DIR } from '../integration/helpers/server.js'; + +setDefaultTimeout(30_000); + +let server; +beforeAll(async () => { server = await startServer(FIXTURE_DIR); }); +afterAll(() => server?.stop()); + +async function lspDiagsFor(filePath, content) { + const result = await server.callTool('validate_code', { file_path: filePath, content, mode: 'quick' }); + const all = [...result.errors, ...result.warnings]; + return all.filter(d => !d.check.startsWith('pos-supervisor:') && d.check !== 'OrphanedPartial'); +} + +function reportShipStatus(check, lspDiags) { + const matched = lspDiags.filter(d => d.check === check); + if (matched.length > 0) { + console.log(` [SHIPPED] ${check} — LSP fires the check. Action items in test header.`); + for (const d of matched.slice(0, 3)) { + console.log(` ${d.check} (${d.severity}): ${d.message?.slice(0, 100)}`); + } + } else { + console.log(` [PENDING] ${check} — still not shipped in this pos-cli. Triggers ready when it lands.`); + } +} + +describePosCli('Coverage probe: InvalidAssignSyntax (upstream PR-A, PR-C)', () => { + it('detects whether trailing-garbage assign syntax is flagged', async () => { + // Triggers from upstream `InvalidAssignSyntax.spec.ts`: stray `}` after a + // filter-array argument inside an assign. Tolerant parser folds back to + // string markup so other checks miss it; the dedicated check catches it. + const content = + "{% assign x = items | map: ['a', 'b'] } %}\n" + + "{% liquid\n assign y = items | join: ',' }\n%}\n"; + const lsp = await lspDiagsFor('app/views/partials/coverage_invalid_assign.liquid', content); + reportShipStatus('InvalidAssignSyntax', lsp); + // Always pass — this is a status probe, not a hard contract. + expect(true).toBe(true); + }); + + it('detects whether structurally-broken assign tags are flagged', async () => { + // Empty markup, missing operator, literal target, empty RHS. + const content = + "{% assign %}\n" + + "{% assign x %}\n" + + "{% assign 'literal' = 5 %}\n" + + "{% assign x = %}\n"; + const lsp = await lspDiagsFor('app/views/partials/coverage_assign_shapes.liquid', content); + reportShipStatus('InvalidAssignSyntax', lsp); + expect(true).toBe(true); + }); +}); + +describePosCli('Coverage probe: InvalidOutputPush (upstream PR-C)', () => { + it('detects whether `<<` in output position is flagged', async () => { + // The `<<` push operator is only valid inside `{% assign %}`. Using it + // in `{{ }}` or `{% echo %}` is invalid — upstream PR-C added a + // dedicated check for this. + const content = + "{{ items << 'x' }}\n" + + "{% echo items << 'x' %}\n"; + const lsp = await lspDiagsFor('app/views/partials/coverage_invalid_output_push.liquid', content); + reportShipStatus('InvalidOutputPush', lsp); + expect(true).toBe(true); + }); +}); + +describePosCli('Coverage probe: parser grammar — bare push form still parses', () => { + it('bare `{% assign arr << item %}` is the only valid push form post-PR-C', async () => { + // Grammar simplification kept the bare push form. This sanity check + // makes sure the parser doesn't regress on the canonical valid input. + const content = "{% assign arr = '' | split: '' %}\n{% assign arr << 'item' %}\n"; + const lsp = await lspDiagsFor('app/views/partials/coverage_bare_push.liquid', content); + const errs = lsp.filter(d => d.severity === 'error'); + if (errs.length > 0) { + console.log(' [REGRESSION CANDIDATE] bare push form produced errors — investigate:'); + for (const e of errs.slice(0, 3)) console.log(` ${e.check}: ${e.message}`); + } + expect(true).toBe(true); + }); +}); diff --git a/tests/upstream/diagnostic-fingerprint.test.js b/tests/upstream/diagnostic-fingerprint.test.js index b1f48c2..f3f751d 100644 --- a/tests/upstream/diagnostic-fingerprint.test.js +++ b/tests/upstream/diagnostic-fingerprint.test.js @@ -119,6 +119,111 @@ const FIXTURES = [ expected_template_fp: '89868bdc426b9a6b4cb483e67bac42b10ab3ed86', expected_params: { category: 'unknown_field_record', field: 'name', type: 'Record' }, }, + + // ── ValidFrontmatter ─ pos-cli 6.0.7 multi-shape check ────────────────────── + // The check emits 8 distinct shapes. We pin one representative per shape so a + // template change in any shape is loud. The file-type label (Page/Form/etc.) + // is intentionally NOT masked — each (category, file_type) pair is a distinct + // analytics axis. The rule_id (set by the rule engine in core/rules/ + // ValidFrontmatter.js) groups across file types when needed. + { + check: 'ValidFrontmatter', + samples: [ + "Missing required frontmatter field 'name' in Form file", + "Missing required frontmatter field 'resource' in Form file", + ], + expected_template: 'Missing required frontmatter field in Form file', + expected_template_fp: '91177b77c72d510aedb42cd4d4e4dd275e2843c9', + expected_params: { category: 'missing_required', field: 'name', file_type: 'Form' }, + }, + { + check: 'ValidFrontmatter', + samples: [ + "Unknown frontmatter field 'cache' in Page file", + "Unknown frontmatter field 'title' in Page file", + ], + expected_template: 'Unknown frontmatter field in Page file', + expected_template_fp: '2461ba62fdf60c6335e84cf44e8f154134df30b5', + expected_params: { category: 'unknown_field', field: 'cache', file_type: 'Page' }, + }, + { + check: 'ValidFrontmatter', + samples: [ + "Layout 'application' does not exist", + "Layout 'modules/core/admin' does not exist", + ], + expected_template: 'Layout does not exist', + expected_template_fp: '20eb602a8f963006b5123f6e53975a17fdcbdd68', + expected_params: { category: 'layout_missing', layout: 'application' }, + }, + { + check: 'ValidFrontmatter', + samples: [ + "Invalid value 'POST' for 'method'. Must be one of: get, post, put, delete, patch", + "Invalid value 'PUT' for 'method'. Must be one of: get, post, put, delete, patch", + ], + expected_template: 'Invalid value for . Must be one of: get, post, put, delete, patch', + expected_template_fp: '055be883904858626da77da6c2a3436cabba3dfa', + expected_params: { + category: 'invalid_enum', + value: 'POST', + field: 'method', + allowed: 'get, post, put, delete, patch', + }, + }, + { + check: 'ValidFrontmatter', + samples: [ + "'layout_name' is deprecated", + "'layout_path' is deprecated", + ], + expected_template: ' is deprecated', + expected_template_fp: 'f34f5eb90a978fc0c05eccf2846ab86decedda7a', + expected_params: { category: 'deprecated_field', field: 'layout_name' }, + }, + { + check: 'ValidFrontmatter', + samples: [ + "Authorization policy 'guest_only' does not exist", + "Authorization policy 'admin_only' does not exist", + ], + expected_template: 'Authorization policy does not exist', + expected_template_fp: '21a6e70cef5fe5a0ac1c991425efd284504e7ecb', + expected_params: { category: 'association_missing', label: 'Authorization policy', name: 'guest_only' }, + }, + + // ── JsonLiteralQuoteStyle ─ single-shot constant message ──────────────────── + { + check: 'JsonLiteralQuoteStyle', + samples: [ + 'Use double quotes for string literals inside object/array literals (e.g. \'{"key": "value"}\', not "{\'key\': \'value\'}").', + ], + expected_template: 'Use double quotes for string literals inside object/array literals (e.g. , not ).', + expected_template_fp: '6330c359bab9fa907940ee6b41fc4f4ebef8dace', + expected_params: {}, + }, + + // ── DuplicateFunctionArguments ─ render and function variants ────────────── + { + check: 'DuplicateFunctionArguments', + samples: [ + "Duplicate argument 'foo' in function tag for partial 'helpers/can_do'.", + "Duplicate argument 'bar' in function tag for partial 'helpers/format'.", + ], + expected_template: 'Duplicate argument in function tag for partial .', + expected_template_fp: '02a96cb3b3010a94fac5eba0d545690f948184bb', + expected_params: { argument: 'foo', tag_kind: 'function', partial: 'helpers/can_do' }, + }, + { + check: 'DuplicateFunctionArguments', + samples: [ + "Duplicate argument 'name' in render tag for partial 'forms/login'.", + "Duplicate argument 'email' in render tag for partial 'forms/signup'.", + ], + expected_template: 'Duplicate argument in render tag for partial .', + expected_template_fp: '49a0e3b1f5cfdc41996898948d303ecc8fc9d710', + expected_params: { argument: 'name', tag_kind: 'render', partial: 'forms/login' }, + }, ]; // Structural (pos-supervisor:*) checks intentionally have NO mask (the tag From dd433335fdc1eed632d0602dc80a3f29f18c880b Mon Sep 17 00:00:00 2001 From: Filip Klosowski Date: Tue, 28 Apr 2026 11:53:46 +0200 Subject: [PATCH 17/20] Rule-engine and hint quality overhaul --- CHANGELOG.md | 295 ++ package-lock.json | 4 +- package.json | 2 +- src/core/diagnostic-pipeline.js | 29 +- src/core/diagnostic-record.js | 42 + src/core/error-enricher.js | 8 +- src/core/fix-generator.js | 16 +- src/core/liquid-parser.js | 61 +- src/core/project-fact-graph.js | 3 + src/core/project-scanner.js | 11 + src/core/rules/DeprecatedTag.js | 139 + src/core/rules/GraphQLVariablesCheck.js | 239 ++ src/core/rules/InvalidLayout.js | 74 + src/core/rules/LiquidHTMLSyntaxError.js | 166 + src/core/rules/MissingAsset.js | 145 + src/core/rules/MissingContentForLayout.js | 44 + src/core/rules/MissingPage.js | 173 + src/core/rules/MissingPartial.js | 133 +- src/core/rules/MissingSlug.js | 42 + src/core/rules/NonGetRenderingPage.js | 181 +- src/core/rules/OrphanedPartial.js | 120 + src/core/rules/ParserBlockingScript.js | 46 + src/core/rules/PartialCallArguments.js | 175 + src/core/rules/SchemaProperty.js | 88 + src/core/rules/SchemaYAML.js | 49 + src/core/rules/TranslationKeyExists.js | 81 +- src/core/rules/TranslationMissingLocaleKey.js | 71 + .../UnrecognizedRenderPartialArguments.js | 71 + src/core/rules/UnusedDocParam.js | 90 + src/core/rules/index.js | 32 + src/core/rules/module-paths.js | 152 + src/core/rules/queries.js | 36 +- src/core/structural-warnings.js | 331 +- src/dashboard.js | 52 +- src/data/hints/MissingPartial.md | 22 +- .../platformos-development-guide-full.md | 3177 --------------- .../resources/platformos-development-guide.md | 3626 +++++++++++++---- .../short-platformos-development-guide.md | 1079 +++++ src/http-server.js | 122 +- src/tools/validate-code.js | 2 + .../structural-rule-attribution.test.js | 9 +- tests/unit/error-enricher-bridge.test.js | 8 +- tests/unit/http-server.test.js | 89 + tests/unit/liquid-parser.test.js | 60 + tests/unit/rules/DeprecatedTag.test.js | 122 + tests/unit/rules/InvalidLayout.test.js | 183 + tests/unit/rules/MissingPartial.test.js | 114 +- tests/unit/rules/NonGetRenderingPage.test.js | 187 + tests/unit/rules/Tier1Rules.test.js | 23 +- tests/unit/rules/Tier3Rules.test.js | 185 + tests/unit/rules/Tier3RulesPhase2.test.js | 204 + tests/unit/rules/Tier3RulesPhase3.test.js | 358 ++ tests/unit/rules/TranslationKeyExists.test.js | 158 + tests/unit/rules/module-paths.test.js | 117 + tests/unit/rules/queries.test.js | 51 +- tests/unit/structural-warnings.test.js | 65 + 56 files changed, 9102 insertions(+), 4060 deletions(-) create mode 100644 src/core/rules/DeprecatedTag.js create mode 100644 src/core/rules/GraphQLVariablesCheck.js create mode 100644 src/core/rules/InvalidLayout.js create mode 100644 src/core/rules/LiquidHTMLSyntaxError.js create mode 100644 src/core/rules/MissingAsset.js create mode 100644 src/core/rules/MissingContentForLayout.js create mode 100644 src/core/rules/MissingPage.js create mode 100644 src/core/rules/MissingSlug.js create mode 100644 src/core/rules/OrphanedPartial.js create mode 100644 src/core/rules/ParserBlockingScript.js create mode 100644 src/core/rules/PartialCallArguments.js create mode 100644 src/core/rules/SchemaProperty.js create mode 100644 src/core/rules/SchemaYAML.js create mode 100644 src/core/rules/TranslationMissingLocaleKey.js create mode 100644 src/core/rules/UnrecognizedRenderPartialArguments.js create mode 100644 src/core/rules/UnusedDocParam.js create mode 100644 src/core/rules/module-paths.js delete mode 100644 src/data/resources/platformos-development-guide-full.md create mode 100644 src/data/resources/short-platformos-development-guide.md create mode 100644 tests/unit/rules/DeprecatedTag.test.js create mode 100644 tests/unit/rules/InvalidLayout.test.js create mode 100644 tests/unit/rules/NonGetRenderingPage.test.js create mode 100644 tests/unit/rules/Tier3Rules.test.js create mode 100644 tests/unit/rules/Tier3RulesPhase2.test.js create mode 100644 tests/unit/rules/Tier3RulesPhase3.test.js create mode 100644 tests/unit/rules/module-paths.test.js diff --git a/CHANGELOG.md b/CHANGELOG.md index d534992..b263f43 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,300 @@ # Changelog +## 0.7.1 — 2026-04-28 + +Fix for the `GraphQLVariablesCheck.required` regression spiral +reported on 2026-04-27 (4 emits / 100 % regression on +`app/lib/commands/contacts/create.liquid` in DEMO) and the dashboard +404 on rule-driven check drilldowns. + +### Fixed — `GraphQLVariablesCheck.required` parser blind spot + +Root cause: a `{% graphql %}` call written inside a `{% liquid %}` +block with multi-line `,` continuation. Both `liquid-html-parser` and +pos-cli's LSP truncate the call at the first newline-comma — +`markup.args` ends up empty and LSP fires +`GraphQLVariablesCheck.required` for every named arg past it. The +agent sees the args in source, our `.required` hint says "add the +variable", agent rewrites cosmetically, LSP fires the same errors. +Loop. + +Three coordinated changes resolve the spiral: + +- **`liquid-parser.js` — graphql call extraction enriched.** Each + `extracted.graphql` entry now carries `args: [name, …]` (from + `markup.args`) and `source_kind: 'tag' | 'liquid_inline' | + 'liquid_multiline_truncated'`. Truncation is detected when the + call's source range starts without `{%` (we are inside `{% liquid + %}`), ends on `,`, and the file text immediately past the call has + another `name:` clause on a subsequent line. New + `classifyGraphqlSourceKind` exported for reuse. Dedup-by-queryName + preserved; if any duplicate call is truncated, the existing entry's + `source_kind` upgrades to the most-pessimistic value so downstream + rules can detect the symptom regardless of which call won the dedup. +- **`rules/GraphQLVariablesCheck.js` — new `parser_blind_spot` + sub-rule (priority 3, before `.required` at 5, confidence 0.95).** + Fires when `direction === 'required'` AND the project graph reports + any graphql call in the file with `source_kind === + 'liquid_multiline_truncated'`. Hint redirects the agent at the + syntactic root cause: convert to single-line `{% graphql … %}` tag + form, or keep it inside `{% liquid %}` but place every named arg on + the same line as `graphql`. Falls through to `.required` when the + call is fine — purely additive, no risk of misfire on legitimate + missing-variable diagnostics. +- **`structural-warnings.js` — new + `pos-supervisor:GraphqlMultilineInLiquidBlock` (severity: error).** + Surfaces the syntactic cause once per truncated call, before LSP + enrichment runs. Reuses `classifyGraphqlSourceKind`. Fires for all + domains; partials still get the existing `GraphqlInPartial` error + on top. + +### Fixed — Dashboard hint endpoint 404 on rule-driven checks + +The dashboard's rule drilldown panel `GET +/api/hints?name=` 404'd for the 12+ rule-driven checks that +have no `src/data/hints/.md` file (`GraphQLVariablesCheck`, +`PartialCallArguments`, `MissingRenderPartialArguments`, +`UnusedDocParam`, `LiquidHTMLSyntaxError`, +`pos-supervisor:InvalidLayout`, `pos-supervisor:MissingSlug`, +`pos-supervisor:MissingContentForLayout`, +`pos-supervisor:SchemaProperty`, `pos-supervisor:SchemaYAML`, +`pos-supervisor:DeprecatedTag`, +`pos-supervisor:TranslationMissingLocaleKey`). These checks are +served by `src/core/rules/.js` modules, not static markdown — but +the endpoint was hardwired to `readFileSync('.md')`. + +- **`http-server.js` — `handleGetHints` now branches.** md file + present → returns `{ source: 'static', content }`. md missing but + rule registry has the check → returns `{ source: 'rule', content, + rule_ids }` with a synthesized markdown reference (per sub-rule: + `id`, priority, truncated `when()` source, footer pointing at + `src/core/rules/.js`). Both miss → 404. List endpoint unions md + filenames with `getAllChecksWithRules()` and adds a `checks: [{ + name, sources: ['static'|'rule', …] }]` companion field. Backward + compat preserved on the `hints` array. +- **`dashboard.js` — drilldown is source-aware.** The hint panel + title surfaces `src/core/rules/.js` for rule-driven checks + instead of the misleading `(src/data/hints/.md)` it always + showed. Action recommendations ("edit X to rewrite the hint") + point at whichever file actually owns the hint. + Knowledge-browser `loadHint` renders a `[RULE-DRIVEN]` / + `[STATIC]` source badge above the body and a readable `404` + message instead of an empty `
      `. Strips `pos-supervisor:`
+  prefix from the rule module path — the rule files are not
+  namespaced.
+
+### Tests
+
+- `tests/unit/liquid-parser.test.js` — 7 new cases covering `args` +
+  `source_kind` for tag, `liquid_inline`,
+  `liquid_multiline_truncated` forms; the
+  comma-ending-without-trailing guard; and the dedup-upgrade path.
+- `tests/unit/rules/Tier3RulesPhase3.test.js` — 5 new cases covering
+  `parser_blind_spot` priority, fall-through to `.required` when not
+  truncated, fall-through when file is unindexed, and fall-through
+  when no graph is available.
+- `tests/unit/structural-warnings.test.js` — 5 new cases covering
+  the `GraphqlMultilineInLiquidBlock` detector against truncated,
+  tag-form, single-line liquid-block, multi-line tag-form, and
+  multiple-occurrence inputs.
+- `tests/unit/http-server.test.js` — 6 new cases covering list
+  union, static md retrieval, rule synthesis, unknown-check 404,
+  prefixed (`pos-supervisor:…`) rule round-trip, and the
+  static-wins-over-rule precedence.
+
+23 new tests, all green. Browser-side dashboard JS verified via
+inline `Function()`-constructor parse.
+
+## 0.7.0 — 2026-04-27
+
+Rule-engine and hint quality overhaul driven by the
+2026-04-27 DEMO performance report (`docs/rule-performance-plan.md`):
+123 diagnostics across 17 sessions, fix-proposal rate 24 %, six rules
+flagged AT RISK or HARMFUL. The headline shift after this release: every
+high-volume bucket-B `.unmatched` check now lands with a stable rule_id
++ structured guidance fix; AT RISK rules ship locale-aware /
+intent-aware hints that converge on the canonical platformOS shape
+instead of producing contradictory advice.
+
+### Fixed — AT RISK rules (Bucket A)
+
+- **`MissingPartial.module_path` (was 0 % resolve / 100 % regress).** Hint
+  diagnosed the symptom but never named a target. Rule now enumerates
+  available module call paths from the filesystem at apply time, runs
+  Levenshtein over them, and ships the top-5 candidates inline. Special
+  case for `modules//commands/build` and `…/check` — the hint
+  explicitly explains build / check are inline phases of the agent's
+  own command and only `execute` is exported by core. Rewrote
+  `MissingPartial.md` STEP 1 to remove the misleading "use core's
+  execute helper" example that drove the over-generalisation. New
+  `src/core/rules/module-paths.js` helper (sync filesystem walk
+  mirroring `module-scanner.scanPublicApi`); `projectDir` plumbed
+  through `enrichCtx` → facts in `validate-code.js` and
+  `error-enricher.js` (both `enrichError` and
+  `bridgeRulesOntoUnattributed`).
+- **`TranslationKeyExists.suggest_nearest` (was 0 % resolve, 6 / 6 ignored).**
+  Three distinct failure modes uncovered, all fixed:
+  - **Locale-prefix double-up.** `flattenYaml` over a properly-rooted
+    `en.yml` produces keys like `en.app.user.title` (the YAML root IS
+    the locale). The rule was suggesting `en.app.user.title` for an
+    agent's `app.usr.title` typo; agents wrote `'en.app.user.title' | t`
+    which Liquid resolved to `en.en.app.user.title` — adopting the fix
+    re-broke the lookup. `translationKeysForLocale` now strips leading
+    `.`; `array_index_misuse` and `create_key` strip from the
+    agent's key before computing `arrayKey` / YAML snippets;
+    `suggest_nearest` matches against bare AND prefixed forms, picks
+    closer. New `stripLocalePrefix(key, locale)` exported from
+    `queries.js`. Hint and fix descriptions now explicitly warn against
+    including the `en.` prefix.
+  - **Levenshtein threshold too loose for dotted keys.** Shared helper's
+    `length * 0.6` admitted distance-10 matches on 20-char keys. Local
+    bound `min(5, length / 3)` per call site — brand-new keys fall
+    through to `create_key` instead of attracting bogus "did you mean"s.
+  - **Defensive `[N]` gate.** Every subrule (`array_index_misuse`,
+    `suggest_nearest`, `create_key`) now gates on raw `diag.message` in
+    addition to `params.key`. Belt-and-suspenders against extractor drift.
+- **`pos-supervisor:NonGetRenderingPage` (was 20 % resolve / 20 %
+  regress, 25 outcomes).** Per the
+  `docs/rule-performance-plan.md` gist analysis: split into three
+  intent-aware subrules + defensive default. `validatePageMethodAndForms`
+  in `structural-warnings.js` (renamed from
+  `validateNonGetRenderingPage`) emits discriminator-prefixed messages;
+  the rule layer routes by regex.
+  - `api_renders_html` — slug under `/api/`, `/_/`, `/internal/` + non-GET
+    method + (HTML present OR `format: json` missing). Hint ships the
+    canonical `format: json` + GraphQL JSON body shape.
+  - `html_on_post` — non-API slug + non-GET method + HTML rendering. Hint
+    disambiguates "landing page" vs "API handler" intents with
+    copy-pasteable Liquid for both.
+  - `get_form_target` — GET page hosts `
      `
+    where X isn't under API prefixes and isn't the page's own slug. Hint
+    routes the agent to `/api/` + auto-creates the API page path.
+  - Form parsing: attribute-order-independent regex; supports single,
+    double, and unquoted attribute values; self-post detection
+    (`action == own slug`) prevents false positives for sanctioned
+    self-post pages. API page emit policy: only layout / partials /
+    HTML tags count as HTML rendering — bare `{{ … }}` in `format: json`
+    pages is the intended JSON serialization, NOT flagged.
+- **`pos-supervisor:InvalidLayout` and `ValidFrontmatter.layout_missing`
+  duplicate-emit + wrong path.** Two checks fired on the same root
+  cause with diverging line numbers (line-only dedup let both through),
+  and the structural emitter hardcoded `.html.liquid` for the create_file
+  proposal — DEMO uses `.liquid`, so agents accepted the fix and the
+  file landed at the wrong path.
+  - `validateLayout` in `structural-warnings.js` now calls
+    `detectLayoutExtension(projectDir, moduleName)` to sample existing
+    layouts and pick `.liquid` vs `.html.liquid` (defaults to `.liquid`
+    when the layouts dir is empty — modern convention).
+  - `extractLayoutPath` in `fix-generator.js` lifts the path verbatim
+    from the message's `Expected file: \`...\`` clause — single source
+    of truth, no per-file re-derivation.
+  - `suppressUpstreamFrontmatterDup` now matches by **layout name** in
+    addition to line — same root cause regardless of line drift.
+  - New `src/core/rules/InvalidLayout.js` rule attaches stable rule_id
+    + matching create_file fix at the corrected path.
+
+### Added — Bucket B `.unmatched` promotions (rule modules)
+
+13 new rule modules covering every bucket-B `.unmatched` check from the
+performance report. Each ships stable rule_id + structured guidance;
+where a heuristic text_edit already exists in `fix-generator.js`, the
+rule emits `guidance` only and the heuristic stays as the actionable
+diff. End-to-end attribution verified via `bridgeRulesOntoUnattributed`.
+
+- **`DeprecatedTag` (covers both upstream LSP and `pos-supervisor:DeprecatedTag`).**
+  Subrules `include` (route to `{% render %}` w/ isolated-scope
+  caveat), `hash_assign` (`{% assign x["k"] = v %}`), `parse_json`
+  (`| parse_json` filter form), default. Defensive when-gates check
+  both `params.tag` and raw message regex (the structural variant has
+  no extractor).
+- **`UnrecognizedRenderPartialArguments`.** Extracts argument + partial
+  from message; emits 3-option decision tree (drop / declare / rename).
+  Disables option B for module partials (read-only).
+- **`SchemaProperty` (8 sub-IDs)** — routes `pos-supervisor:SchemaProperty`
+  emits by regex into `builtin_conflict` / `duplicate_name` /
+  `invalid_identifier` / `snake_case` / `upload_options` /
+  `missing_field` / `misleading_key` / `default`.
+- **`SchemaYAML`, `MissingSlug`, `MissingContentForLayout`** —
+  promotions of existing fix-generator heuristics; rule emits guidance,
+  heuristic still owns the text_edit.
+- **`ParserBlockingScript`** — defer / async / end-of-body decision tree.
+- **`TranslationMissingLocaleKey`** — extracts locale from message,
+  emits before/after YAML wrap recipe.
+- **`MissingAsset` (3 subrules)** —
+  `missing_subdir_prefix` (high confidence: bare `logo.png` matches
+  existing `images/logo.png`) → `suggest_nearest` (Levenshtein) →
+  `create_file`. Replaces the heuristic's blind-create proposal.
+- **`OrphanedPartial`** — emits `delete_file` fix when graph has 0
+  callers; softer guidance for layouts; cites `pending_files`
+  workflow for in-progress refactors.
+- **`MissingPage` (2 subrules)** — `typo` (Levenshtein vs graph page
+  slugs) → `default` (3-option decision tree + create_file at inferred
+  path). Handles root route correctly (omit `slug:`).
+- **`LiquidHTMLSyntaxError` (5 subrules)** — `unknown_tag` (Levenshtein
+  vs `tagsIndex.platformOSTags()`) → `for_loop_args` →
+  `missing_assign` → `inline_literal` → `default`.
+- **`PartialCallArguments` (4 subrules)** — highest-volume bucket-B
+  check (28 emits in DEMO). New extractor parses both
+  `Required parameter X must be passed to (render|function) call` and
+  `Unknown parameter X passed to ...` shapes. Subrules
+  `required_render`, `required_function`, `unknown_render`,
+  `unknown_function` ship copy-pasteable forwarding patterns + the
+  canonical drop / declare / rename resolution. Cross-references the
+  sibling `MissingRenderPartialArguments` /
+  `UnrecognizedRenderPartialArguments` checks (which carry the partial
+  path when they co-fire).
+- **`GraphQLVariablesCheck` (2 subrules + default)** — new extractor
+  for `Required parameter X must be passed to GraphQL call` /
+  `Unknown parameter X passed to GraphQL call`. Hint surfaces a
+  per-call **signature block** when the file's `graphql_calls` are
+  indexed — lists every operation invoked + its declared
+  `$var: Type` list parsed from the .graphql operation header.
+- **`UnusedDocParam`** — caller-aware confidence: 0.8 when graph shows
+  zero callers (option B = remove `@param` is safe); 0.65 when callers
+  exist (removing the declaration becomes a contract change). Hint
+  references the pipeline's `suppressUnusedDocParams` so agents
+  understand surviving emits aren't the named-arg false positive.
+  No text_edit — contract change with cross-file blast radius is not
+  safe for the rule layer to automate.
+
+### Added — query helpers
+
+- `assetNames(graph)` — list every indexed asset path
+  (`MissingAsset.suggest_nearest`).
+- `stripLocalePrefix(key, locale)` — translation-key normalisation.
+- `parseModulePath(name)` exported from `MissingPartial.js` —
+  splits `modules///` for analytics callers.
+
+### Changed — graph plumbing
+
+- `project-scanner.js` and `project-fact-graph.js` now propagate
+  `graphql_calls` to **pages, partials, AND layouts** (previously
+  commands/queries only). Without this, `GraphQLVariablesCheck`'s
+  signature block was empty for the most common caller — API pages
+  emitting JSON.
+
+### Changed — extractors
+
+- New `extractParams` entries for `PartialCallArguments`,
+  `GraphQLVariablesCheck`, `UnusedDocParam` in `diagnostic-record.js`.
+
+### Tests
+
+130 new unit tests across 7 new rule-test files
+(`module-paths.test.js`, extended `MissingPartial.test.js`,
+`TranslationKeyExists.test.js`, `Tier3Rules.test.js`,
+`Tier3RulesPhase2.test.js`, `Tier3RulesPhase3.test.js`,
+`DeprecatedTag.test.js`, `NonGetRenderingPage.test.js`,
+`InvalidLayout.test.js`). Existing
+`error-enricher-bridge.test.js`, `Tier1Rules.test.js`, and
+`structural-rule-attribution.test.js` updated to match the
+three-subrule shape.
+
+Total rule entries: **86 (vs 47 at 0.6.0)**. Full suite at release:
+1802 / 1803 unit pass (the lone failure is a pre-existing
+`load_development_guide` drift unrelated to this release); 88 / 88
+targeted integration pass.
+
 ## 0.6.0 — 2026-04-24
 
 Analytics pipeline overhaul + neuro-symbolic engine rounds out. Headline numbers on the DEMO project between 2026-04-23 and 2026-04-24: fix-proposal rate rose from effectively 0 (the emit loop was reading the wrong field) to 45 / 99 (45%); classified fix adoption rose from 0 to 31; confidence coverage from 0% to 89% of emits; rule performance table from 3 entries at baseline to 30+; health score from 91 to 95/100.
diff --git a/package-lock.json b/package-lock.json
index 5613760..184a65a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@platformos/pos-supervisor",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@platformos/pos-supervisor",
-      "version": "0.6.0",
+      "version": "0.7.1",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
         "@platformos/liquid-html-parser": "^0.0.17",
diff --git a/package.json b/package.json
index 7f3a7e9..19f6f01 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@platformos/pos-supervisor",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "platformOS domain-specific MCP server for LLM agents",
   "type": "module",
   "bin": {
diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js
index 2d65a83..96109db 100644
--- a/src/core/diagnostic-pipeline.js
+++ b/src/core/diagnostic-pipeline.js
@@ -1032,16 +1032,35 @@ export function stampDefaultsOn(result) {
  * @returns {number} count of suppressed diagnostics
  */
 export function suppressUpstreamFrontmatterDup(result) {
+  // Two matching axes — line (the default) AND layout name (parsed from the
+  // message). The line-match alone misses cases where upstream and our
+  // structural emitter disagree by ±1 line (frontmatter edge cases, leading
+  // whitespace, line-zero anchoring), which is exactly what the DEMO data
+  // showed: both `pos-supervisor:InvalidLayout` and
+  // `ValidFrontmatter.layout_missing` fired with diverging line values, so
+  // the agent saw two contradictory hints for the same root cause.
   const ourLines = new Set();
+  const ourInvalidLayoutNames = new Set();
   for (const d of [...result.errors, ...result.warnings]) {
-    if (d.check === 'pos-supervisor:InvalidLayout' ||
-        d.check === 'pos-supervisor:InvalidFrontMatter') {
+    if (d.check === 'pos-supervisor:InvalidLayout' || d.check === 'pos-supervisor:InvalidFrontMatter') {
       ourLines.add(d.line);
     }
+    if (d.check === 'pos-supervisor:InvalidLayout') {
+      const layoutName = d.message?.match(/^Layout `([^`]+)` not found/)?.[1];
+      if (layoutName) ourInvalidLayoutNames.add(layoutName);
+    }
   }
-  if (ourLines.size === 0) return 0;
-
-  const isRedundant = (d) => d.check === 'ValidFrontmatter' && ourLines.has(d.line);
+  if (ourLines.size === 0 && ourInvalidLayoutNames.size === 0) return 0;
+
+  const isRedundant = (d) => {
+    if (d.check !== 'ValidFrontmatter') return false;
+    if (ourLines.has(d.line)) return true;
+    // Layout-name match: the upstream `Layout 'X' does not exist` shape
+    // names the same layout `X` that pos-supervisor:InvalidLayout already
+    // flagged. The two diagnostics describe identical root cause.
+    const layoutName = d.message?.match(/^Layout ['"`]([^'"`]+)['"`] does not exist$/)?.[1];
+    return !!layoutName && ourInvalidLayoutNames.has(layoutName);
+  };
   const eRemoved = result.errors.filter(isRedundant).length;
   const wRemoved = result.warnings.filter(isRedundant).length;
   const removed = eRemoved + wRemoved;
diff --git a/src/core/diagnostic-record.js b/src/core/diagnostic-record.js
index a89fad2..74af617 100644
--- a/src/core/diagnostic-record.js
+++ b/src/core/diagnostic-record.js
@@ -228,6 +228,48 @@ const EXTRACTORS = Object.freeze({
     return { is_function_call: /function call/i.test(message) ? 'true' : 'false' };
   },
 
+  PartialCallArguments(message) {
+    // Two distinct LSP message shapes:
+    //   "Required parameter  must be passed to (render|function|GraphQL) call"
+    //   "Unknown parameter  passed to (render|function|GraphQL) call"
+    // Both carry the param name and the call kind; neither carries the
+    // partial / function path (the sibling MissingRenderPartialArguments
+    // does, when the agent is rendering a partial).
+    const requiredMatch = message.match(/^Required parameter\s+([A-Za-z_][\w]*)\s+must be passed to (\w+)\s+call/i);
+    const unknownMatch  = message.match(/^Unknown parameter\s+([A-Za-z_][\w]*)\s+passed to (\w+)\s+call/i);
+    const m = requiredMatch || unknownMatch;
+    if (!m) return {};
+    const callKind = m[2].toLowerCase();
+    return {
+      param_name: m[1],
+      direction: requiredMatch ? 'required' : 'unknown',
+      call_kind: callKind,                                      // 'render' | 'function' | 'graphql'
+      is_function_call: callKind === 'function' ? 'true' : 'false',
+    };
+  },
+
+  GraphQLVariablesCheck(message) {
+    // LSP shape mirrors PartialCallArguments but always carries the
+    // GraphQL call kind. We surface the same params so a generic param-
+    // mismatch handler (rule layer) can route on `direction` + the
+    // operation name once we plumb it.
+    const requiredMatch = message.match(/^Required parameter\s+([A-Za-z_][\w]*)\s+must be passed to GraphQL call/i);
+    const unknownMatch  = message.match(/^Unknown parameter\s+([A-Za-z_][\w]*)\s+passed to GraphQL call/i);
+    const m = requiredMatch || unknownMatch;
+    if (!m) return {};
+    return {
+      param_name: m[1],
+      direction: requiredMatch ? 'required' : 'unknown',
+      call_kind: 'graphql',
+    };
+  },
+
+  UnusedDocParam(message) {
+    // LSP shape: "The parameter 'name' is defined but not used in this file."
+    const m = message.match(/^The parameter\s+['"`]([A-Za-z_][\w]*)['"`]\s+is defined but not used/i);
+    return m ? { param_name: m[1] } : {};
+  },
+
   ValidFrontmatter(message) {
     // pos-cli 6.0.7 ships a single check that emits eight distinct shapes.
     // We classify into a `category` so the rule engine can route to a
diff --git a/src/core/error-enricher.js b/src/core/error-enricher.js
index 02b6ee2..db3aace 100644
--- a/src/core/error-enricher.js
+++ b/src/core/error-enricher.js
@@ -28,7 +28,7 @@ function extractHoverText(result) {
  * @param {object} ctx.schemaIndex
  * @returns {Promise} Enriched diagnostic
  */
-export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore, content, _hoverCache, factGraph, filePath }) {
+export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore, content, _hoverCache, factGraph, filePath, projectDir }) {
   const result = { ...diagnostic };
 
   // 1. Hint set per-check below with template vars; fallback for unhandled checks at end
@@ -58,7 +58,7 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI
     const params = extractParams(diagnostic.check, diagnostic.message);
     const tmplFp = templateOf(diagnostic.check, diagnostic.message);
     const diag = { check: diagnostic.check, params, message: diagnostic.message, file: filePath, line: diagnostic.line, column: diagnostic.column ?? 0, template_fp: tmplFp };
-    const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore };
+    const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore, projectDir };
     const ruleResult = runRules(diag, facts);
     if (ruleResult) {
       result.hint = ruleResult.hint_md;
@@ -558,10 +558,10 @@ export async function enrichAll(diagnostics, ctx) {
  * scoring.
  */
 export function bridgeRulesOntoUnattributed(result, ctx) {
-  const { filePath, content, factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore } = ctx;
+  const { filePath, content, factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore, projectDir } = ctx;
   if (!factGraph) return;
 
-  const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore };
+  const facts = { graph: factGraph, filtersIndex, objectsIndex, tagsIndex, schemaIndex, analyticsStore, projectDir };
 
   const apply = (d) => {
     if (d.rule_id) return;                   // already attributed
diff --git a/src/core/fix-generator.js b/src/core/fix-generator.js
index 1084f66..ee230ee 100644
--- a/src/core/fix-generator.js
+++ b/src/core/fix-generator.js
@@ -1107,9 +1107,19 @@ function fixInvalidFrontMatter(diagnostic, content) {
 }
 
 function extractLayoutPath(message) {
-  const match = message?.match(/`([^`]+)`.*not found/);
-  if (!match) return 'app/views/layouts/application.html.liquid';
-  return `app/views/layouts/${match[1]}.html.liquid`;
+  // The structural emitter (`validateLayout` in structural-warnings.js) has
+  // access to projectDir and detects whether the project standardised on
+  // `.liquid` or `.html.liquid` for layouts. It bakes the full expected
+  // file path into the message ("Expected file: `app/views/layouts/X.liquid`"),
+  // so the right thing here is to lift that path verbatim — never re-derive.
+  const expected = message?.match(/Expected file:\s*`([^`]+)`/);
+  if (expected) return expected[1];
+
+  // Defensive fallback: only used when the message shape changes upstream.
+  // We bias toward `.liquid` (the modern shape) and ignore module layouts —
+  // an agent shouldn't be creating files inside an installed module anyway.
+  const layoutName = message?.match(/`([^`]+)`.*not found/)?.[1];
+  return layoutName ? `app/views/layouts/${layoutName}.liquid` : 'app/views/layouts/application.liquid';
 }
 
 /**
diff --git a/src/core/liquid-parser.js b/src/core/liquid-parser.js
index cccdc77..7feb677 100644
--- a/src/core/liquid-parser.js
+++ b/src/core/liquid-parser.js
@@ -83,9 +83,28 @@ export function extractAllFromAST(ast) {
           const markup = node.markup;
           if (markup?.type === NodeTypes.GraphQLMarkup) {
             const gqlPath = markup.graphql;
-            if (gqlPath?.type === NodeTypes.String && !seenGQL.has(gqlPath.value)) {
-              seenGQL.add(gqlPath.value);
-              graphql.push({ variable: markup.name, queryName: gqlPath.value });
+            if (gqlPath?.type === NodeTypes.String) {
+              const queryName = gqlPath.value;
+              const sourceKind = classifyGraphqlSourceKind(node);
+              const args = extractArgsFromMarkup(markup);
+              if (seenGQL.has(queryName)) {
+                // Same op called twice. Keep the first entry but upgrade
+                // source_kind to the most pessimistic value across calls so
+                // downstream rules can detect truncation regardless of which
+                // call won the dedup.
+                if (sourceKind === 'liquid_multiline_truncated') {
+                  const existing = graphql.find(g => g.queryName === queryName);
+                  if (existing) existing.source_kind = 'liquid_multiline_truncated';
+                }
+              } else {
+                seenGQL.add(queryName);
+                graphql.push({
+                  variable: markup.name,
+                  queryName,
+                  args,
+                  source_kind: sourceKind,
+                });
+              }
             }
           }
         }
@@ -134,6 +153,42 @@ function extractArgsFromMarkup(markup) {
     .map(a => a.name);
 }
 
+/**
+ * Classify the surface form of a `{% graphql %}` call.
+ *
+ *   'tag'                         — `{% graphql ... %}` (with delimiters).
+ *   'liquid_inline'               — inside a `{% liquid %}` block, single-line.
+ *   'liquid_multiline_truncated'  — inside a `{% liquid %}` block, written
+ *                                   with a comma + newline continuation. The
+ *                                   liquid-html-parser truncates the call at
+ *                                   the first newline-comma, so `markup.args`
+ *                                   silently drops every argument past it —
+ *                                   and pos-cli's LSP diagnostic check has
+ *                                   the same blind spot. The agent sees the
+ *                                   args in source; both parsers don't.
+ *
+ * Detection criterion for the truncated form: source range starts without
+ * `{%` (we are inside a `{% liquid %}` block), the visible source text ends
+ * on a comma, AND the immediately trailing characters in the file contain
+ * another `name:` clause on a subsequent line. The trailing-text check is
+ * the load-bearing signal — without it a legitimate inline call that just
+ * happens to end on a comma (rare, but possible) would be misclassified.
+ */
+export function classifyGraphqlSourceKind(node) {
+  const src = typeof node?.source === 'string' ? node.source : '';
+  const start = node?.position?.start ?? 0;
+  const end = node?.position?.end ?? 0;
+  const text = src.slice(start, end);
+  if (text.startsWith('{%')) return 'tag';
+  if (text.trimEnd().endsWith(',')) {
+    const trail = src.slice(end, end + 200);
+    if (/\n\s*[A-Za-z_]\w*\s*:/.test(trail)) {
+      return 'liquid_multiline_truncated';
+    }
+  }
+  return 'liquid_inline';
+}
+
 function extractArgsFromMarkupString(markupStr) {
   const args = [];
   const afterPartial = markupStr.replace(/^["'][^"']+["']\s*,?\s*/, '');
diff --git a/src/core/project-fact-graph.js b/src/core/project-fact-graph.js
index 7791d7f..2a27e9b 100644
--- a/src/core/project-fact-graph.js
+++ b/src/core/project-fact-graph.js
@@ -42,6 +42,7 @@ class ProjectFactGraph {
         slug: page.slug, method: page.method, layout: page.layout,
         renders: page.renders, render_calls: page.render_calls,
         function_calls: page.function_calls,
+        graphql_calls: page.graphql_calls,
       });
     }
 
@@ -50,6 +51,7 @@ class ProjectFactGraph {
         params: partial.params, renders: partial.renders,
         render_calls: partial.render_calls,
         function_calls: partial.function_calls, rendered_by: partial.rendered_by,
+        graphql_calls: partial.graphql_calls,
       });
     }
 
@@ -82,6 +84,7 @@ class ProjectFactGraph {
         renders: layout.renders,
         render_calls: layout.render_calls,
         function_calls: layout.function_calls,
+        graphql_calls: layout.graphql_calls,
       });
     }
 
diff --git a/src/core/project-scanner.js b/src/core/project-scanner.js
index 68d0694..bd0d968 100644
--- a/src/core/project-scanner.js
+++ b/src/core/project-scanner.js
@@ -55,6 +55,11 @@ export async function scanProject(projectDir) {
           renders: file.structural.renders,
           render_calls: file.structural.renderCalls,
           function_calls: file.functionCalls,
+          // API pages (`method: post`, `format: json`) commonly carry a
+          // `{% graphql %}` body directly. Indexing graphql_calls here
+          // lets rule-engine consumers resolve the operation from any
+          // caller — same shape as commands/queries.
+          graphql_calls: file.structural.graphql,
         };
         break;
       }
@@ -66,6 +71,9 @@ export async function scanProject(projectDir) {
           renders: file.structural.renders,
           render_calls: file.structural.renderCalls,
           function_calls: file.functionCalls,
+          // Partials may host `{% graphql %}` calls (data-fetching helpers).
+          // Index for the same reason as pages above.
+          graphql_calls: file.structural.graphql,
           rendered_by: [],
         };
         break;
@@ -95,6 +103,9 @@ export async function scanProject(projectDir) {
           renders: file.structural.renders,
           render_calls: file.structural.renderCalls,
           function_calls: file.functionCalls,
+          // Same rationale as pages/partials — layouts may invoke graphql
+          // for nav data, etc.
+          graphql_calls: file.structural.graphql,
         };
         break;
       }
diff --git a/src/core/rules/DeprecatedTag.js b/src/core/rules/DeprecatedTag.js
new file mode 100644
index 0000000..ef01d27
--- /dev/null
+++ b/src/core/rules/DeprecatedTag.js
@@ -0,0 +1,139 @@
+/**
+ * DeprecatedTag rules — both the upstream LSP `DeprecatedTag` check (emitted
+ * by pos-cli for `{% include %}`, `{% parse_json %}`, etc.) AND the
+ * pos-supervisor structural variant `pos-supervisor:DeprecatedTag` (raised
+ * by `structural-warnings.detectDeprecatedTags` when the upstream check is
+ * silent for a tag we still want flagged).
+ *
+ * Rule_id pinning: every emit of either check now lands as
+ * `DeprecatedTag.` (or `.default`) in analytics. Before this module both
+ * checks were `*.unmatched`, so adoption + regression rates were collapsed
+ * across very different tags (`include` is ~100 % auto-fixable, `hash_assign`
+ * needs careful per-line edits, `parse_json` needs filter-syntax migration).
+ *
+ * Fix policy:
+ *   - `include`     → `text_edit` is owned by `ConvertIncludeToRender` (different
+ *                     check name, sibling rule). The deprecated-tag rule
+ *                     emits `guidance` only — duplicating the rename here
+ *                     would compete with that module.
+ *   - `hash_assign` → fix-generator's `fixDeprecatedTag` produces a
+ *                     `hash_assign` → `assign` literal text_edit. We emit
+ *                     `guidance` so it isn't a duplicate; the heuristic
+ *                     edit complements the explanation.
+ *   - `parse_json`  → no live text_edit yet (the `| parse_json` filter form
+ *                     is structural, not a single-token swap). `guidance`
+ *                     plus an explicit migration recipe is the best signal
+ *                     short of an AST rewrite.
+ *   - default       → fallback for any other deprecated tag the upstream
+ *                     adds in future without a dedicated subrule.
+ */
+
+const RULES_FOR_CHECK = (checkName) => [
+  {
+    id: `${ruleIdPrefix(checkName)}.include`,
+    check: checkName,
+    priority: 10,
+    when: (diag) => /\binclude\b/.test(diag.params?.tag ?? '') || /\binclude\b/.test(diag.message ?? ''),
+    apply: () => ({
+      rule_id: `${ruleIdPrefix(checkName)}.include`,
+      hint_md:
+        '`{% include %}` is deprecated. Replace with `{% render %}` everywhere in this file. ' +
+        '`{% render %}` has **isolated scope** — variables from the parent are NOT inherited; ' +
+        'pass each one explicitly: `{% render \'partial\', name: name, items: items %}`. ' +
+        'Exception: includes that pull in a module helper meant to share scope (auth, redirects) — ' +
+        'leave those alone; the heuristic fix-generator detects this pattern and proposes guidance ' +
+        'instead of a rename.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Rename every `{% include \'X\' %}` in this file to `{% render \'X\',  %}`. ' +
+          'List the partial\'s declared `@param` names and pass each explicitly — ' +
+          'isolated scope means undeclared vars come through as `nil`.',
+      }],
+      confidence: 0.95,
+    }),
+  },
+
+  {
+    id: `${ruleIdPrefix(checkName)}.hash_assign`,
+    check: checkName,
+    priority: 10,
+    when: (diag) => /hash_assign/.test(diag.params?.tag ?? '') || /\bhash_assign\b/.test(diag.message ?? ''),
+    apply: () => ({
+      rule_id: `${ruleIdPrefix(checkName)}.hash_assign`,
+      hint_md:
+        '`{% hash_assign x, key: value %}` is deprecated. Use the bracket-assign form ' +
+        '`{% assign x["key"] = value %}` (or dot form `{% assign x.key = value %}` for ' +
+        'identifier keys). Both produce the same hash — the new form is plain `assign`.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Replace `{% hash_assign x, key: value %}` with `{% assign x["key"] = value %}`. ' +
+          'For dotted identifiers: `{% assign x.key = value %}`. ' +
+          'The heuristic fix-generator emits the literal `hash_assign` → `assign` text_edit; ' +
+          'apply it then update the argument shape from `, key: value` to `["key"] = value`.',
+      }],
+      confidence: 0.85,
+    }),
+  },
+
+  {
+    id: `${ruleIdPrefix(checkName)}.parse_json`,
+    check: checkName,
+    priority: 10,
+    when: (diag) => /parse_json/.test(diag.params?.tag ?? '') || /\bparse_json\b/.test(diag.message ?? ''),
+    apply: () => ({
+      rule_id: `${ruleIdPrefix(checkName)}.parse_json`,
+      hint_md:
+        '`{% parse_json x %}…{% endparse_json %}` is deprecated. Use the filter form ' +
+        '`{% assign x = \'\' | parse_json %}` (single-line) or build the literal with ' +
+        '`{% capture json %}…{% endcapture %}{% assign x = json | parse_json %}` for ' +
+        'multi-line payloads. The filter is exact-equivalent semantically.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Migrate `{% parse_json x %}{ … }{% endparse_json %}` to ' +
+          '`{% assign x = \'{ … }\' | parse_json %}`. For multi-line payloads use ' +
+          '`{% capture body %}{ … }{% endcapture %}{% assign x = body | parse_json %}` so the ' +
+          'JSON is left literal — `parse_json` accepts strings, not block contents.',
+      }],
+      confidence: 0.85,
+    }),
+  },
+
+  {
+    id: `${ruleIdPrefix(checkName)}.default`,
+    check: checkName,
+    priority: 100,
+    when: () => true,
+    apply: (diag) => {
+      const tag = diag.params?.tag ?? null;
+      const replacement = diag.params?.replacement ?? null;
+      const tagSpan = tag ? `\`{% ${tag} %}\`` : 'this tag';
+      const replSpan = replacement ? `Use \`{% ${replacement} %}\` instead.` : '';
+      return {
+        rule_id: `${ruleIdPrefix(checkName)}.default`,
+        hint_md:
+          `${tagSpan} is deprecated in platformOS. ${replSpan} ` +
+          `Read the upstream message — it usually names the replacement and behavioral changes ` +
+          `(e.g. isolated scope for \`render\`). Fix every occurrence in this file in one pass; ` +
+          `leaving a single instance re-fires the check on the next write.`,
+        fixes: [],
+        confidence: 0.7,
+      };
+    },
+  },
+];
+
+function ruleIdPrefix(checkName) {
+  // `pos-supervisor:DeprecatedTag` → rule_id starts with the bare check name
+  // so analytics aggregation across the upstream + structural variants stays
+  // readable. Storing rule_id as `pos-supervisor:DeprecatedTag.include` would
+  // break a couple of dashboard regexes that strip the colon segment.
+  return checkName.replace(/^pos-supervisor:/, '');
+}
+
+export const rules = [
+  ...RULES_FOR_CHECK('DeprecatedTag'),
+  ...RULES_FOR_CHECK('pos-supervisor:DeprecatedTag'),
+];
diff --git a/src/core/rules/GraphQLVariablesCheck.js b/src/core/rules/GraphQLVariablesCheck.js
new file mode 100644
index 0000000..07a7104
--- /dev/null
+++ b/src/core/rules/GraphQLVariablesCheck.js
@@ -0,0 +1,239 @@
+/**
+ * GraphQLVariablesCheck rules — `{% graphql result = 'op_name', $X: Y %}`
+ * passed (or omitted) a variable that doesn't match the .graphql operation's
+ * declared signature.
+ *
+ * Pre-rule the check landed as `.unmatched` (3 emits in DEMO, 100 %
+ * resolution but 0 % adoption — the LSP message named the variable but
+ * carried no actionable fix). The rule extracts variable + direction
+ * (required vs unknown) from the message and, when the file has graphql
+ * calls indexed by the project graph, surfaces the operation's full
+ * variable signature so the agent can pick the right value type.
+ *
+ * Subrules:
+ *   • GraphQLVariablesCheck.parser_blind_spot — call lives inside a
+ *       `{% liquid %}` block with multi-line `,` continuation. Both
+ *       liquid-html-parser and pos-cli's LSP truncate the call at the first
+ *       newline-comma; LSP fires `.required` for every arg past it. The
+ *       agent sees the args in source, our default `.required` hint says
+ *       "add the arg" — agent enters a regression spiral. This sub-rule
+ *       fires first when the project graph reports the file's graphql call
+ *       with `source_kind === 'liquid_multiline_truncated'` and steers the
+ *       agent at the syntactic root cause instead. (Reproduced in DEMO
+ *       2026-04-27, 4 emits / 100 % regression.)
+ *   • GraphQLVariablesCheck.required        — agent forgot a `$var` argument.
+ *   • GraphQLVariablesCheck.unknown         — agent passed an undeclared `$var`.
+ *   • GraphQLVariablesCheck.default         — extractor failed; bare hint.
+ *
+ * Fix policy: guidance-only; the deterministic edit needs the call's
+ * argument list which the rule layer doesn't have.
+ */
+
+export const rules = [
+  {
+    id: 'GraphQLVariablesCheck.parser_blind_spot',
+    check: 'GraphQLVariablesCheck',
+    priority: 3,
+    when: (diag, facts) => isParserBlindSpot(diag, facts),
+    apply: (diag, facts) => buildParserBlindSpotHint(diag, facts),
+  },
+  {
+    id: 'GraphQLVariablesCheck.required',
+    check: 'GraphQLVariablesCheck',
+    priority: 5,
+    when: (diag) => diag.params?.direction === 'required',
+    apply: (diag, facts) => buildRequiredHint(diag, facts),
+  },
+  {
+    id: 'GraphQLVariablesCheck.unknown',
+    check: 'GraphQLVariablesCheck',
+    priority: 6,
+    when: (diag) => diag.params?.direction === 'unknown',
+    apply: (diag, facts) => buildUnknownHint(diag, facts),
+  },
+  {
+    id: 'GraphQLVariablesCheck.default',
+    check: 'GraphQLVariablesCheck',
+    priority: 100,
+    when: () => true,
+    apply: (diag) => ({
+      rule_id: 'GraphQLVariablesCheck.default',
+      hint_md:
+        `\`{% graphql %}\` variable mismatch. Open the called .graphql operation under \`app/graphql/\` ` +
+        `and read the operation header — variables declared as \`$name: Type\` (no leading \`$\` is wrong). ` +
+        `Required → add the argument to the tag (\`{% graphql r = 'op', name: value %}\`); Unknown → drop it.`,
+      fixes: [{
+        type: 'guidance',
+        description:
+          `Open the .graphql file's operation header to see the full \`$variable: Type\` signature, then ` +
+          `pass each required variable as a named argument on the \`{% graphql %}\` tag.`,
+      }],
+      confidence: 0.5,
+    }),
+  },
+];
+
+/**
+ * True when the diagnostic looks like the multi-line truncation false-flag:
+ *   • LSP fired `direction: required` (it sees no args at all).
+ *   • Project graph has a graphql call from this file whose extracted
+ *     `source_kind === 'liquid_multiline_truncated'`.
+ *
+ * `source_kind` is populated by `liquid-parser.classifyGraphqlSourceKind`
+ * during scan — see liquid-parser.js for the detection criterion. Falsy
+ * graphs / unindexed files / unrelated source kinds all fall through to the
+ * downstream `.required` rule, so this predicate is purely additive.
+ */
+function isParserBlindSpot(diag, facts) {
+  if (diag?.params?.direction !== 'required') return false;
+  const node = facts?.graph?.nodeByPath?.(diag?.file);
+  const calls = node?.graphql_calls ?? [];
+  return calls.some(c => c?.source_kind === 'liquid_multiline_truncated');
+}
+
+function buildParserBlindSpotHint(diag, facts) {
+  const param = diag?.params?.param_name ?? '';
+  const sigBlock = signatureBlock(diag, facts);
+  return {
+    rule_id: 'GraphQLVariablesCheck.parser_blind_spot',
+    hint_md:
+      `\`{% graphql %}\` call appears to pass \`${param}\`, but the parser cannot see it. ` +
+      `The call lives inside a \`{% liquid %}\` block written with multi-line \`,\` ` +
+      `continuation — both pos-cli's check and the AST parser stop at the first newline-comma, ` +
+      `so every named argument past it is silently dropped.\n\n` +
+      `Do NOT keep adding the argument — it is already there in source. **Fix the syntax**:\n\n` +
+      '```liquid\n' +
+      `{% graphql result = '', ${param}: ${param}, ... %}    # tag form, args on one line\n` +
+      '```\n' +
+      `or, if you must keep it inside \`{% liquid %}\`, put every named arg on the SAME line as ` +
+      `\`graphql\`:\n\n` +
+      '```liquid\n' +
+      `{% liquid\n` +
+      `  graphql result = '', ${param}: ${param}, email: email, ...\n` +
+      `%}\n` +
+      '```' +
+      sigBlock,
+    fixes: [{
+      type: 'guidance',
+      description:
+        `Convert the multi-line \`graphql\` call to a single-line form. Either move it out of ` +
+        `\`{% liquid %}\` into \`{% graphql ... %}\` tag delimiters, or keep it inside the block ` +
+        `but place every \`name: value\` argument on the same line as \`graphql\`. The arguments ` +
+        `you wrote are correct — only the line breaks are dropping them.${diagFiles(diag, facts)}`,
+    }],
+    confidence: 0.95,
+    see_also: {
+      tool: 'domain_guide',
+      args: { domain: 'graphql' },
+      reason: 'Multi-line `{% graphql %}` continuation inside `{% liquid %}` is silently truncated. domain_guide(graphql) shows the canonical tag form.',
+    },
+  };
+}
+
+function buildRequiredHint(diag, facts) {
+  const param = diag.params?.param_name ?? '';
+  const sigBlock = signatureBlock(diag, facts);
+  return {
+    rule_id: 'GraphQLVariablesCheck.required',
+    hint_md:
+      `\`{% graphql %}\` call is missing required variable \`${param}\`. The operation declares ` +
+      `\`$${param}: \` in its header — every non-optional variable (no \`= default\`) MUST be passed ` +
+      `at the call site.\n\n` +
+      `Add to the tag:\n` +
+      '```liquid\n' +
+      `{% graphql result = '', ${param}: ${param} %}    # forward caller scope\n` +
+      `{% graphql result = '', ${param}: \"value\" %}    # literal\n` +
+      `{% graphql result = '', ${param}: context.params.${param} %}  # request param\n` +
+      '```' +
+      sigBlock,
+    fixes: [{
+      type: 'guidance',
+      description:
+        `Add \`${param}: \` to the \`{% graphql %}\` tag. The value must match the declared ` +
+        `GraphQL type — pass a string for \`String!\`, an integer for \`Int!\`, an object literal for ` +
+        `input types, etc.${diagFiles(diag, facts)}`,
+    }],
+    confidence: 0.75,
+    see_also: {
+      tool: 'domain_guide',
+      args: { domain: 'graphql' },
+      reason: 'GraphQL call variable mismatch. domain_guide(graphql) covers $variable signatures and value forwarding.',
+    },
+  };
+}
+
+function buildUnknownHint(diag, facts) {
+  const param = diag.params?.param_name ?? '';
+  const sigBlock = signatureBlock(diag, facts);
+  return {
+    rule_id: 'GraphQLVariablesCheck.unknown',
+    hint_md:
+      `\`{% graphql %}\` call passes \`${param}\` but the operation does NOT declare \`$${param}\`. ` +
+      `Undeclared variables are silently dropped at call time — this is dead data that may mask a typo.\n\n` +
+      `Pick one fix:\n` +
+      `  A) **Drop** \`${param}: ...\` from the \`{% graphql %}\` tag in this file.\n` +
+      `  B) **Declare** \`$${param}: \` in the .graphql operation's variable list (and use it in ` +
+      `the body — orphan declarations themselves trigger \`GraphQLCheck\`).\n` +
+      `  C) **Rename** \`${param}\` to match an existing operation variable — common cause is a typo.` +
+      sigBlock,
+    fixes: [{
+      type: 'guidance',
+      description:
+        `Pick: (A) drop \`${param}: \` from the call, (B) add \`$${param}: \` to the .graphql ` +
+        `operation header, or (C) rename \`${param}\` to a declared variable.${diagFiles(diag, facts)}`,
+    }],
+    confidence: 0.75,
+    see_also: {
+      tool: 'domain_guide',
+      args: { domain: 'graphql' },
+      reason: 'GraphQL call passes an undeclared variable. domain_guide(graphql) covers $variable signatures.',
+    },
+  };
+}
+
+/**
+ * Build a markdown block listing the declared variables of every graphql
+ * operation called from `diag.file`. Empty string when the file is not
+ * indexed or has no graphql_calls.
+ *
+ * Uses the graph's `graphql_calls` (which carries `{ variable, queryName }`
+ * per call) and the per-operation node's `args` list (parsed from the
+ * `.graphql` file's `query Foo($x: String!) { ... }` header).
+ */
+function signatureBlock(diag, facts) {
+  const sigs = collectSignatures(diag, facts);
+  if (sigs.length === 0) return '';
+  const list = sigs.map(s => {
+    const args = s.args.length === 0
+      ? '(no variables)'
+      : s.args.map(a => `\`$${a.name}: ${a.type}\``).join(', ');
+    return `  • \`${s.queryName}\` — ${args}`;
+  }).join('\n');
+  return `\n\nGraphQL operation(s) called from this file:\n${list}`;
+}
+
+function diagFiles(diag, facts) {
+  const sigs = collectSignatures(diag, facts);
+  if (sigs.length !== 1) return '';
+  return ` Reference: \`app/graphql/${sigs[0].queryName}.graphql\`.`;
+}
+
+function collectSignatures(diag, facts) {
+  const graph = facts?.graph;
+  const filePath = diag?.file;
+  if (!graph || !filePath) return [];
+  const node = graph.nodeByPath(filePath);
+  if (!node) return [];
+  const calls = node.graphql_calls ?? [];
+  const out = [];
+  const seen = new Set();
+  for (const call of calls) {
+    const queryName = typeof call === 'string' ? call : call?.queryName;
+    if (!queryName || seen.has(queryName)) continue;
+    seen.add(queryName);
+    const opNode = graph.nodeByKey('graphql', queryName);
+    if (!opNode) continue;
+    out.push({ queryName, args: opNode.args ?? [] });
+  }
+  return out;
+}
diff --git a/src/core/rules/InvalidLayout.js b/src/core/rules/InvalidLayout.js
new file mode 100644
index 0000000..d811866
--- /dev/null
+++ b/src/core/rules/InvalidLayout.js
@@ -0,0 +1,74 @@
+/**
+ * pos-supervisor:InvalidLayout rule — page front-matter references a layout
+ * that doesn't exist on disk.
+ *
+ * Pre-rule the check landed as `.unmatched` even though fix-generator's
+ * `fixStructuralCheck` already produced a `create_file` proposal. Pre-task-4
+ * the proposal hardcoded the `.html.liquid` extension which DOES NOT match
+ * many projects (DEMO included) — agents accepted the fix, the file landed
+ * at the wrong path, and the original error never resolved.
+ *
+ * Task 4 fixed the path in the structural emitter (it now embeds the right
+ * extension via `detectLayoutExtension`) and made `extractLayoutPath`
+ * lift the path verbatim from the message. This rule attaches stable
+ * attribution + a guidance fix that explains the two valid resolutions
+ * (rename the layout reference vs create the missing layout file).
+ *
+ * Pairs with `ValidFrontmatter.layout_missing` (upstream LSP). The dedup
+ * pass `suppressUpstreamFrontmatterDup` drops the upstream copy so only
+ * this rule fires per offending page.
+ */
+
+const MSG_RE = /^Layout `([^`]+)` not found\. Expected file: `([^`]+)`\./;
+
+export const rules = [
+  {
+    id: 'InvalidLayout.default',
+    check: 'pos-supervisor:InvalidLayout',
+    priority: 100,
+    when: () => true,
+    apply: (diag) => {
+      const m = (diag.message ?? '').match(MSG_RE);
+      const layoutName = m?.[1] ?? null;
+      const expectedPath = m?.[2] ?? null;
+
+      const layoutSpan = layoutName ? `\`${layoutName}\`` : 'the referenced layout';
+      const pathSpan = expectedPath ? `\`${expectedPath}\`` : 'the expected layout file';
+
+      const hint =
+        `${layoutSpan} is not on disk. The structural emitter resolved the canonical path to ` +
+        `${pathSpan} (extension picked to match the project's existing layouts).\n\n` +
+        `Two resolutions:\n` +
+        `  • **Layout reference is wrong** — fix \`layout: ${layoutName ?? ''}\` in this page's ` +
+        `front matter. Run \`project_map\` to see which layouts exist.\n` +
+        `  • **Layout file is missing** — create ${pathSpan}. Every layout MUST contain ` +
+        `\`{{ content_for_layout }}\` exactly once (and may add named \`{% yield 'name' %}\` slots).`;
+
+      return {
+        rule_id: 'InvalidLayout.default',
+        hint_md: hint,
+        fixes: expectedPath
+          ? [{
+              type: 'create_file',
+              path: expectedPath,
+              description:
+                `Create ${pathSpan} with at least \`{{ content_for_layout }}\` so pages using ` +
+                `\`layout: ${layoutName ?? ''}\` render. Verify the layout name is intentional first — ` +
+                `a typo in the page front matter is a more common cause than a genuinely missing layout.`,
+            }]
+          : [{
+              type: 'guidance',
+              description:
+                `Either fix the layout name in the page's front matter, or create the layout file. ` +
+                `Run \`project_map\` to see which layouts exist.`,
+            }],
+        confidence: 0.85,
+        see_also: {
+          tool: 'domain_guide',
+          args: { domain: 'layouts' },
+          reason: 'Layout file conventions — required `{{ content_for_layout }}`, named yield slots, locations.',
+        },
+      };
+    },
+  },
+];
diff --git a/src/core/rules/LiquidHTMLSyntaxError.js b/src/core/rules/LiquidHTMLSyntaxError.js
new file mode 100644
index 0000000..cbd340a
--- /dev/null
+++ b/src/core/rules/LiquidHTMLSyntaxError.js
@@ -0,0 +1,166 @@
+/**
+ * LiquidHTMLSyntaxError rules — pos-cli surfaces a varied set of parser
+ * errors under one check name:
+ *   - Unknown tag
+ *   - For-loop argument shape mismatch
+ *   - Missing `=` in graphql/function assigns (heuristic owns text_edit)
+ *   - Inline array/hash literal in tag arguments
+ *   - Unclosed Liquid block / mismatched quotes
+ *
+ * Pre-rule every emit landed as `.unmatched` even though the messages
+ * carry a clear discriminator. The rule routes by message shape and emits
+ * subrule-specific guidance so analytics distinguish the very different
+ * resolution rates (unknown_tag at ~100 % vs nested array literal where the
+ * agent often misreads the cause).
+ *
+ * Fix policy:
+ *   - missing_assign — heuristic in fix-generator already produces a
+ *     text_edit. Rule emits guidance; precedence drops the heuristic
+ *     `guidance` if any (it isn't there in this branch).
+ *   - All others — guidance only; no deterministic AST rewrite.
+ */
+
+import { nearestByLevenshtein } from './queries.js';
+
+export const rules = [
+  {
+    id: 'LiquidHTMLSyntaxError.unknown_tag',
+    check: 'LiquidHTMLSyntaxError',
+    priority: 5,
+    when: (diag) => /Unknown tag/i.test(diag.message ?? ''),
+    apply: (diag, facts) => {
+      const m = diag.message.match(/Unknown tag\s+['"`]?(\w+)['"`]?/i);
+      const badTag = m?.[1] ?? null;
+      const tagsIndex = facts?.tagsIndex;
+
+      let didYouMean = '';
+      if (badTag && tagsIndex?.platformOSTags) {
+        const known = tagsIndex.platformOSTags().map(t => t.name);
+        const nearest = nearestByLevenshtein(badTag, known, 3);
+        if (nearest.length > 0) {
+          const list = nearest.map(n => `\`{% ${n.name} %}\``).join(', ');
+          didYouMean = ` Did you mean: ${list}?`;
+        }
+      }
+
+      const tagSpan = badTag ? `\`{% ${badTag} %}\`` : 'this tag';
+      return {
+        rule_id: 'LiquidHTMLSyntaxError.unknown_tag',
+        hint_md:
+          `${tagSpan} is not a recognised Liquid tag in platformOS.${didYouMean}\n\n` +
+          `Common causes: typo in the tag name, custom tag from another framework (Shopify Liquid extras ` +
+          `like \`{% layout %}\`, \`{% schema %}\` are NOT supported), or a stale rename. ` +
+          `If the tag is custom: platformOS does not support custom tags — restructure as a partial ` +
+          `(\`{% render %}\`) or filter.`,
+        fixes: [{
+          type: 'guidance',
+          description: badTag
+            ? `Replace ${tagSpan} with the correct tag name (see suggestions in the hint), or ` +
+              `restructure if it was a Shopify-only tag.`
+            : `Read the upstream message — it names the unknown tag. Replace it with a valid platformOS ` +
+              `tag or restructure the logic.`,
+        }],
+        confidence: 0.85,
+      };
+    },
+  },
+
+  {
+    id: 'LiquidHTMLSyntaxError.for_loop_args',
+    check: 'LiquidHTMLSyntaxError',
+    priority: 10,
+    when: (diag) => /Arguments must be provided in the format `for in/i.test(diag.message ?? ''),
+    apply: (diag) => {
+      const m = diag.message.match(/Invalid\/Unknown arguments:\s*(.+)$/i);
+      const badArgs = m?.[1]?.trim() ?? null;
+      const argsSpan = badArgs ? `\`${badArgs}\`` : 'the offending argument(s)';
+      return {
+        rule_id: 'LiquidHTMLSyntaxError.for_loop_args',
+        hint_md:
+          `\`{% for %}\` arguments must follow the form ` +
+          `\`for  in  [reversed] [limit:N] [offset:N]\`. ` +
+          `${argsSpan} ${badArgs ? 'are' : 'is'} not a recognised positional or named argument.\n\n` +
+          `Frequent root cause: a Liquid filter (\`| t\`, \`| split\`, etc.) appears INSIDE the ` +
+          `\`for ... in ...\` clause. The Liquid parser does not accept filter pipelines in the loop ` +
+          `header — assign the filtered value first, then iterate.\n\n` +
+          `Wrong: \`{% for item in 'k' | t %}\`  Right: \`{% assign items = 'k' | t %}{% for item in items %}\`. ` +
+          `Wrong: \`{% for word in str | split: ',' %}\`  Right: \`{% assign words = str | split: ',' %}{% for word in words %}\`.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Move the filter pipeline out of the \`for in \` clause: ` +
+            `\`{% assign items =  %}\` first, then \`{% for item in items %}\`. ` +
+            `For nested loops over translation arrays, see the TranslationKeyExists.array_index_misuse ` +
+            `pattern.`,
+        }],
+        confidence: 0.85,
+      };
+    },
+  },
+
+  {
+    id: 'LiquidHTMLSyntaxError.missing_assign',
+    check: 'LiquidHTMLSyntaxError',
+    priority: 15,
+    when: (diag) => /\{%\s*(?:graphql|function)/.test(diag.message ?? '') && /=/.test(diag.message ?? ''),
+    apply: () => ({
+      rule_id: 'LiquidHTMLSyntaxError.missing_assign',
+      hint_md:
+        '`{% graphql %}` and `{% function %}` require an assignment target. The syntax is ' +
+        '`{% graphql result = \'query_name\' %}` and `{% function result = \'path/to/helper\', arg: val %}` — ' +
+        'the `result =` part captures the call output and is not optional.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Add ` =` between the tag name and the call path. ' +
+          '`{% graphql records = \'q\' %}` / `{% function record = \'helper\', x: 1 %}`. ' +
+          'fix-generator emits the literal text_edit for the missing-`=` shape — accept it.',
+      }],
+      confidence: 0.9,
+    }),
+  },
+
+  {
+    id: 'LiquidHTMLSyntaxError.inline_literal',
+    check: 'LiquidHTMLSyntaxError',
+    priority: 20,
+    when: (diag) => /(?:array|hash|object|literal|inline)/i.test(diag.message ?? '') &&
+                    /\{%\s*(?:render|function|graphql)/.test(diag.message ?? ''),
+    apply: () => ({
+      rule_id: 'LiquidHTMLSyntaxError.inline_literal',
+      hint_md:
+        'Inline `[…]` array literals and `{ … }` hash literals are NOT accepted as tag arguments. ' +
+        'Liquid\'s tag parser only takes named scalars and pre-assigned variables. Build the literal ' +
+        'in a preceding `{% assign %}` then pass the variable.\n\n' +
+        'Wrong: `{% render \'p\', items: [] %}`  Right: `{% assign items = [] %}{% render \'p\', items: items %}`.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Pre-assign the literal: `{% assign items = […] %}` (or `{% assign cfg = { … } %}` for hashes), ' +
+          'then pass `items` (or `cfg`) by name in the render/function/graphql tag.',
+      }],
+      confidence: 0.85,
+    }),
+  },
+
+  {
+    id: 'LiquidHTMLSyntaxError.default',
+    check: 'LiquidHTMLSyntaxError',
+    priority: 100,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'LiquidHTMLSyntaxError.default',
+      hint_md:
+        'Liquid parser error. Read the upstream message — it names the line and column. ' +
+        'Common causes:\n' +
+        '  • Unclosed block (`{% if %}` without `{% endif %}`, `{% for %}` without `{% endfor %}`).\n' +
+        '  • Inside `{% liquid %}` blocks each statement is on its own line with NO delimiters.\n' +
+        '  • Mismatched quotes — every `\'` and `"` must be paired on the same logical token.\n' +
+        '  • HTML and Liquid syntax interleaved unsafely (e.g. `
      ` ' +
+        'is fine; `
      ` is not).\n\n' +
+        'Fix the FIRST reported error — later errors often cascade from it.',
+      fixes: [],
+      confidence: 0.5,
+    }),
+  },
+];
diff --git a/src/core/rules/MissingAsset.js b/src/core/rules/MissingAsset.js
new file mode 100644
index 0000000..cf1f8d5
--- /dev/null
+++ b/src/core/rules/MissingAsset.js
@@ -0,0 +1,145 @@
+/**
+ * MissingAsset rules — `{{ 'foo.css' | asset_url }}` or
+ * `{% include_asset 'foo.js' %}` references a file that doesn't exist
+ * under `app/assets/`.
+ *
+ * Pre-rule the check landed as `.unmatched`; fix-generator's
+ * `fixMissingAsset` produced an unconditional `create_file` proposal
+ * (`app/assets/`). That's wrong roughly half the time — the more
+ * common case is a typo or a missing subdirectory prefix
+ * (`logo.png` vs `images/logo.png`). The DEMO data showed 0 % resolution,
+ * 33 % adoption-but-`partial` (agent ran the create_file then realized the
+ * intended file was elsewhere).
+ *
+ * Subrules:
+ *   5  — missing_subdir_prefix: bare filename like `logo.png` matches an
+ *        existing asset under a known subdir (`images/logo.png`).
+ *        Highest-confidence "this is a typo, fix the reference" signal.
+ *   10 — suggest_nearest: Levenshtein vs `assetNames(graph)`. Catches
+ *        ordinary typos (`maain.css` → `main.css`).
+ *  100 — create_file: nothing close, propose creating it. Mirrors the
+ *        existing heuristic so analytics gets stable rule_id even when no
+ *        match exists.
+ */
+
+import { assetNames, nearestByLevenshtein } from './queries.js';
+
+const KNOWN_ASSET_SUBDIRS = ['images', 'styles', 'scripts', 'fonts', 'media'];
+
+export const rules = [
+  {
+    id: 'MissingAsset.missing_subdir_prefix',
+    check: 'MissingAsset',
+    priority: 5,
+    when: (diag, facts) => {
+      const wanted = parseAssetPath(diag.message);
+      if (!wanted || wanted.includes('/')) return false;
+      const all = assetNames(facts?.graph);
+      return all.some(a => assetMatchesBareName(a, wanted));
+    },
+    apply: (diag, facts) => {
+      const wanted = parseAssetPath(diag.message);
+      const all = assetNames(facts.graph);
+      const matches = all.filter(a => assetMatchesBareName(a, wanted));
+      const best = matches[0];
+      const matchList = matches.slice(0, 5).map(m => `\`${m}\``).join(', ');
+      return {
+        rule_id: 'MissingAsset.missing_subdir_prefix',
+        hint_md:
+          `\`${wanted}\` is not at \`app/assets/${wanted}\` directly, but a file with this name lives under ` +
+          `a subdirectory: ${matchList}. \`asset_url\` paths are relative to \`app/assets/\` AND must include ` +
+          `the subdirectory (\`images/\`, \`styles/\`, \`scripts/\`, \`fonts/\`, \`media/\`). Fix the reference, ` +
+          `don't create a new file.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Replace \`'${wanted}'\` with \`'${best}'\` in the \`asset_url\` filter (or \`include_asset\` tag). ` +
+            `Do NOT create a new \`app/assets/${wanted}\` — the file already exists at \`app/assets/${best}\`.`,
+        }],
+        confidence: 0.9,
+      };
+    },
+  },
+
+  {
+    id: 'MissingAsset.suggest_nearest',
+    check: 'MissingAsset',
+    priority: 10,
+    when: (diag, facts) => {
+      const wanted = parseAssetPath(diag.message);
+      if (!wanted) return false;
+      const all = assetNames(facts?.graph);
+      if (all.length === 0) return false;
+      return nearestByLevenshtein(wanted, all, 3).length > 0;
+    },
+    apply: (diag, facts) => {
+      const wanted = parseAssetPath(diag.message);
+      const all = assetNames(facts.graph);
+      const nearest = nearestByLevenshtein(wanted, all, 3);
+      const best = nearest[0].name;
+      const list = nearest.map(n => `\`${n.name}\``).join(', ');
+      return {
+        rule_id: 'MissingAsset.suggest_nearest',
+        hint_md:
+          `\`${wanted}\` not found under \`app/assets/\`. Did you mean: ${list}? ` +
+          `If the reference is a typo, fix it. If you genuinely need a new asset, create the file ` +
+          `at \`app/assets/${wanted}\`.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Replace \`'${wanted}'\` with \`'${best}'\` in the \`asset_url\` filter (or \`include_asset\` tag). ` +
+            `Distance ${nearest[0].distance} — verify the suggestion before applying.`,
+        }],
+        confidence: nearest[0].distance <= 2 ? 0.85 : 0.65,
+      };
+    },
+  },
+
+  {
+    id: 'MissingAsset.create_file',
+    check: 'MissingAsset',
+    priority: 100,
+    when: () => true,
+    apply: (diag) => {
+      const wanted = parseAssetPath(diag.message);
+      const targetPath = wanted ? `app/assets/${wanted}` : 'app/assets/';
+      return {
+        rule_id: 'MissingAsset.create_file',
+        hint_md:
+          `\`${wanted ?? 'asset'}\` does not exist under \`app/assets/\`. ` +
+          `\`asset_url\` paths are relative to \`app/assets/\` AND must include the subdirectory ` +
+          `(\`images/\`, \`styles/\`, \`scripts/\`, \`fonts/\`, \`media/\`). ` +
+          `If this is a module-shipped asset the file may already exist inside the module's ` +
+          `\`public/assets/\` — module assets are referenced through the same \`asset_url\` filter ` +
+          `and should resolve automatically; if they don't, the module isn't installed.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Create the asset at \`${targetPath}\`, OR (more likely) fix the reference — module assets ` +
+            `live under \`modules//public/assets/\` and resolve through the same \`asset_url\` filter ` +
+            `without any path prefix. Only create a new file when you control the asset and it is genuinely missing.`,
+        }],
+        confidence: 0.6,
+      };
+    },
+  },
+];
+
+function parseAssetPath(message) {
+  if (!message) return null;
+  const m = message.match(/['"`]([^'"`]+)['"`]\s+does not exist/);
+  return m ? m[1] : null;
+}
+
+function assetMatchesBareName(assetPath, bareName) {
+  // `assetPath` is relative to app/assets/, e.g. `images/logo.png`. We're
+  // matching when the LAST segment equals the bare name AND the leading
+  // segment is one of the conventional asset subdirs. This avoids
+  // false-positive matches against unrelated nested files
+  // (e.g. agent wrote `data.json` and we'd otherwise match `vendor/x/data.json`).
+  const slash = assetPath.indexOf('/');
+  if (slash < 0) return false;
+  const subdir = assetPath.slice(0, slash);
+  const tail = assetPath.slice(slash + 1);
+  return tail === bareName && KNOWN_ASSET_SUBDIRS.includes(subdir);
+}
diff --git a/src/core/rules/MissingContentForLayout.js b/src/core/rules/MissingContentForLayout.js
new file mode 100644
index 0000000..1b1f3cb
--- /dev/null
+++ b/src/core/rules/MissingContentForLayout.js
@@ -0,0 +1,44 @@
+/**
+ * pos-supervisor:MissingContentForLayout rule — layouts missing
+ * `{{ content_for_layout }}`. Pre-rule the check landed as `.unmatched`
+ * even though fix-generator's `fixMissingContentForLayout` already inserts
+ * the placeholder after `` (or at line 0 if no body tag exists).
+ *
+ * The rule attaches stable attribution and a `guidance` fix that explains
+ * the relationship between `{{ content_for_layout }}` and named `{% yield %}`
+ * slots — the heuristic's `insert` text_edit is the actionable diff.
+ */
+
+export const rules = [
+  {
+    id: 'MissingContentForLayout.default',
+    check: 'pos-supervisor:MissingContentForLayout',
+    priority: 100,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'MissingContentForLayout.default',
+      hint_md:
+        'Every layout MUST include `{{ content_for_layout }}` exactly once — that is where the page body ' +
+        'is rendered into. Without it, pages using this layout serve only the layout chrome (header / nav / ' +
+        'footer) and the page-specific content silently disappears.\n\n' +
+        'Distinction:\n' +
+        '  • `{{ content_for_layout }}` — the implicit "page body" slot. Every layout has exactly one.\n' +
+        '  • `{% yield "name" %}` — named, optional slots a page can fill via `{% content_for "name" %}`. ' +
+        'Use these for sidebars, head injection, etc. Adding more named slots does NOT replace the ' +
+        'implicit body slot.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Insert `{{ content_for_layout }}` once in the layout — typically right after the `` tag. ' +
+          'The heuristic fix-generator emits the literal `insert` text_edit; accept it. ' +
+          'Add named `{% yield "name" %}` slots only when pages need extra fill points.',
+      }],
+      confidence: 0.95,
+      see_also: {
+        tool: 'domain_guide',
+        args: { domain: 'layouts' },
+        reason: 'Layouts domain guide explains content_for_layout vs yield and shows the canonical layout shape.',
+      },
+    }),
+  },
+];
diff --git a/src/core/rules/MissingPage.js b/src/core/rules/MissingPage.js
new file mode 100644
index 0000000..ad5e199
--- /dev/null
+++ b/src/core/rules/MissingPage.js
@@ -0,0 +1,173 @@
+/**
+ * MissingPage rule — `link_to '/foo'`, `redirect_to '/foo'`, etc. references
+ * a route the project doesn't serve. The diagnostic-pipeline already
+ * suppresses references whose page is on disk (via `buildPageRouteIndex` +
+ * `resolvePageRoute`); by the time the diagnostic reaches this rule the
+ * route is genuinely missing OR served with a different method.
+ *
+ * Pre-rule the check landed as `.unmatched`. The bare LSP message
+ * (`No page found for route '/foo' (GET)`) gives the agent no signal on
+ * whether to fix the route, change method, or create the page.
+ *
+ * Subrules:
+ *   10  — typo: extracted route is Levenshtein-close to an indexed page slug
+ *         → suggest renaming the reference.
+ *   100 — default: emit a structured decision tree (typo / new page / method
+ *         mismatch) and propose a `create_file` for the most-likely page path.
+ *
+ * Note: route ↔ method mismatch detection lives in the pipeline upstream.
+ * This rule treats every surviving diagnostic as a "page truly missing"
+ * outcome and points the agent at the three valid resolutions.
+ */
+
+import { nearestByLevenshtein } from './queries.js';
+
+export const rules = [
+  {
+    id: 'MissingPage.typo',
+    check: 'MissingPage',
+    priority: 10,
+    when: (diag, facts) => {
+      const parsed = parseMissingPageMessage(diag.message);
+      if (!parsed) return false;
+      const candidates = pageRouteCandidates(facts?.graph);
+      if (candidates.length === 0) return false;
+      return nearestByLevenshtein(parsed.route, candidates, 3).length > 0;
+    },
+    apply: (diag, facts) => {
+      const { route, method } = parseMissingPageMessage(diag.message);
+      const candidates = pageRouteCandidates(facts.graph);
+      const nearest = nearestByLevenshtein(route, candidates, 3);
+      const best = nearest[0];
+      if (!best || best.distance > 3) return null;
+      const list = nearest.map(n => `\`/${n.name}\``).join(', ');
+      return {
+        rule_id: 'MissingPage.typo',
+        hint_md:
+          `No page serves \`/${route}\` (${method.toUpperCase()}), but the project has nearby routes: ${list}. ` +
+          `If the reference is a typo, fix it; if the page is genuinely missing, scaffold it now.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Replace \`'/${route}'\` with \`'/${best.name}'\` in the link/redirect (or correct the slug ` +
+            `to match \`/${route}\` if you actually meant the latter). Distance ${best.distance} — ` +
+            `verify the correction before applying.`,
+        }],
+        confidence: best.distance <= 1 ? 0.85 : 0.7,
+      };
+    },
+  },
+
+  {
+    id: 'MissingPage.default',
+    check: 'MissingPage',
+    priority: 100,
+    when: () => true,
+    apply: (diag) => {
+      const parsed = parseMissingPageMessage(diag.message);
+      const route = parsed ? parsed.route : null;       // can legitimately be '' for root
+      const method = parsed?.method ?? 'get';
+      const haveRoute = route !== null;
+      const inferredPath = haveRoute ? routeToPagePath(route) : 'app/views/pages/.liquid';
+      const routeSpan = haveRoute ? `\`/${route}\`` : 'this route';
+      // The root page conventionally has either an empty `slug:` or none at
+      // all (the file-path → route fallback covers it). Distinguish the
+      // wording so an empty `slug:` line doesn't read like a typo.
+      const slugBlurb = !haveRoute
+        ? '(set `slug:` to the desired URL)'
+        : route === ''
+          ? '(omit `slug:` — the root page lives at `app/views/pages/index.liquid` and serves `/` automatically)'
+          : `(\`slug: ${route}\`)`;
+
+      const hint =
+        `${routeSpan} (${method.toUpperCase()}) is not served by any page in this project. ` +
+        `Three valid resolutions:\n` +
+        `  • **Typo in the reference** — fix the slug at the call site (\`link_to\`, \`redirect_to\`, ` +
+        `\`form action\`, etc.).\n` +
+        `  • **New page** — scaffold a page at \`${inferredPath}\` ${slugBlurb}. ` +
+        `The file path alone determines the route when no \`slug:\` front-matter key is present.\n` +
+        `  • **Method mismatch** — a page may serve this URL for a different HTTP method (e.g. agent ` +
+        `wrote ${method.toUpperCase()} but the page is GET-only). Open the candidate page and check ` +
+        `its \`method:\` front-matter key.\n\n` +
+        `If you're mid-feature and the page is in the plan but not yet on disk, pass ` +
+        `\`pending_pages=["${inferredPath}"]\` to validate_code so this stops firing while you write it.`;
+
+      return {
+        rule_id: 'MissingPage.default',
+        hint_md: hint,
+        fixes: [{
+          type: 'create_file',
+          path: inferredPath,
+          description:
+            `Create the missing page at \`${inferredPath}\` (slug: \`${route ?? ''}\`). ` +
+            `Only apply if you intend to add this page — if the route was a typo at the call site, ` +
+            `fix the reference instead.`,
+        }],
+        confidence: 0.6,
+        see_also: {
+          tool: 'domain_guide',
+          args: { domain: 'pages' },
+          reason: 'Pages domain guide explains slug/method semantics and the file-path → route mapping.',
+        },
+      };
+    },
+  },
+];
+
+/**
+ * Mirror of `parseMissingPageMessage` from page-route-index.js — kept local
+ * to avoid creating a load-order dependency between the rule engine and the
+ * pipeline. The shape matches; behaviour is identical for the messages we
+ * receive at this stage. Returns null when the message can't be parsed.
+ */
+function parseMissingPageMessage(message) {
+  if (!message) return null;
+  const quoted = message.match(/['"`]([^'"`]+)['"`]/);
+  if (!quoted) return null;
+  let route = quoted[1].trim();
+  while (route.startsWith('/')) route = route.slice(1);
+  if (route === 'index') route = '';
+  if (route.endsWith('/index')) route = route.slice(0, -'/index'.length);
+  const methodMatch = message.match(/\(([A-Za-z]+)\)/);
+  const method = (methodMatch?.[1] ?? 'get').toLowerCase();
+  return { route, method };
+}
+
+/**
+ * Enumerate every page slug the project graph knows. Prefers the explicit
+ * front-matter slug when present; falls back to deriving from the file path
+ * exactly the way the route index does.
+ */
+function pageRouteCandidates(graph) {
+  if (!graph) return [];
+  const out = [];
+  for (const node of graph.nodesByType('page')) {
+    if (typeof node.slug === 'string' && node.slug.length > 0) {
+      out.push(normalize(node.slug));
+    } else if (node.path) {
+      out.push(routeFromPath(node.path));
+    }
+  }
+  return [...new Set(out)];
+}
+
+function normalize(raw) {
+  let p = raw.trim();
+  while (p.startsWith('/')) p = p.slice(1);
+  if (p === 'index') return '';
+  if (p.endsWith('/index')) p = p.slice(0, -'/index'.length);
+  return p;
+}
+
+function routeFromPath(absLikePath) {
+  const stripped = absLikePath
+    .replace(/^app\/views\/pages\//, '')
+    .replace(/\.html\.liquid$/, '')
+    .replace(/\.liquid$/, '');
+  return normalize(stripped);
+}
+
+function routeToPagePath(route) {
+  if (!route || route === '') return 'app/views/pages/index.liquid';
+  return `app/views/pages/${route}.liquid`;
+}
diff --git a/src/core/rules/MissingPartial.js b/src/core/rules/MissingPartial.js
index 7c8d0d0..e2f498b 100644
--- a/src/core/rules/MissingPartial.js
+++ b/src/core/rules/MissingPartial.js
@@ -8,6 +8,11 @@
  *   40 — create_file: generate create_file fix with scaffold
  */
 import { classifyPath, nearestByLevenshtein, partialNames, partialsReachableFrom } from './queries.js';
+import {
+  installedModules,
+  moduleCallPathsByCategory,
+  moduleInstalled,
+} from './module-paths.js';
 
 export const rules = [
   {
@@ -18,21 +23,118 @@ export const rules = [
       const name = diag.params?.partial;
       return !!name && name.startsWith('modules/');
     },
-    apply: (diag) => {
+    apply: (diag, facts) => {
       const name = diag.params.partial;
-      const moduleName = name.split('/')[1];
+      const parsed = parseModulePath(name);
+      const projectDir = facts?.projectDir ?? null;
+
+      // 1. Module not installed → list known modules + Levenshtein.
+      if (parsed.moduleName && projectDir && !moduleInstalled(projectDir, parsed.moduleName)) {
+        const installed = installedModules(projectDir);
+        const nearest = nearestByLevenshtein(parsed.moduleName, installed, 3);
+        const list = installed.length > 0
+          ? `Installed modules: ${installed.map(m => `\`${m}\``).join(', ')}.`
+          : `No modules are installed under \`modules/\`.`;
+        const didYouMean = nearest.length > 0
+          ? ` Did you mean \`${nearest[0].name}\`?`
+          : '';
+        return {
+          rule_id: 'MissingPartial.module_path',
+          hint_md:
+            `Module \`${parsed.moduleName}\` is not installed in this project. ${list}${didYouMean} ` +
+            `Module paths look like \`modules///\` — check the module name first.`,
+          fixes: [{
+            type: 'guidance',
+            description:
+              `Module \`${parsed.moduleName}\` not installed. Either install it (\`pos-cli modules install ${parsed.moduleName}\`), ` +
+              `pick a different module from the installed list, or move the call into a project-local file under \`app/lib/\`.`,
+          }],
+          confidence: 0.9,
+          see_also: {
+            tool: 'project_map',
+            args: {},
+            reason: `Module '${parsed.moduleName}' not installed. project_map enumerates installed modules and project-local commands/queries.`,
+          },
+        };
+      }
+
+      // 2. Module installed → enumerate exports and reason about the bad path.
+      const moduleName = parsed.moduleName;
+      const exportsByCategory = projectDir && moduleName
+        ? moduleCallPathsByCategory(projectDir, moduleName)
+        : null;
+
+      const buildCheckSpecial = parsed.category === 'commands'
+        && (parsed.rest === 'build' || parsed.rest === 'check');
+
+      const allExports = exportsByCategory
+        ? Object.values(exportsByCategory).flat()
+        : [];
+
+      // Levenshtein over every callable in the module, not just the
+      // (possibly mistyped) category — agents land in the wrong category
+      // bucket all the time (e.g. `commands/find_user` when the export is
+      // `queries/users/find`).
+      const nearest = allExports.length > 0
+        ? nearestByLevenshtein(name, allExports, 5)
+        : [];
+
+      const candidatesBlock = nearest.length > 0
+        ? nearest.map(n => `\`${n.name}\``).join(', ')
+        : '(no close matches in this module)';
+
+      let lead;
+      if (buildCheckSpecial) {
+        // The original failure mode the report flagged: agents copy the
+        // `modules/core/commands/execute` shortcut, then assume `…/build`
+        // and `…/check` exist as siblings. They don't — build/check are
+        // inline phases of the *caller's* command, written next to
+        // execute.liquid in the agent's own `app/lib/commands//`
+        // tree. Only `execute` is exported by core for the simple-create
+        // shortcut.
+        lead =
+          `\`${name}\` does not exist. \`build\` and \`check\` are **inline phases of your own command**, ` +
+          `not module-level helpers — write them as \`build.liquid\` / \`check.liquid\` next to your \`execute.liquid\` ` +
+          `under \`app/lib/commands//\`. Only \`modules/${moduleName}/commands/execute\` is exported by core ` +
+          `(simple-create shortcut). For complex flows (multi-step orchestration, validation chains) ` +
+          `keep build/check inline.`;
+      } else {
+        lead = `\`${name}\` is not exported by module \`${moduleName}\`.`;
+      }
+
+      const categorySummary = exportsByCategory
+        ? Object.entries(exportsByCategory)
+            .filter(([, paths]) => paths.length > 0)
+            .map(([cat, paths]) => `${cat} (${paths.length})`)
+            .join(', ')
+        : null;
+
+      const hint =
+        `${lead}\n\n` +
+        `Closest matches in \`${moduleName}\`: ${candidatesBlock}.` +
+        (categorySummary ? `\nExported categories: ${categorySummary}.` : '') +
+        `\nCall \`module_info(${moduleName}, api)\` to read the full export list with @param signatures.`;
+
+      const fixDescription = buildCheckSpecial
+        ? `Remove the \`{% function ... = '${name}', ... %}\` call and inline the build/check logic ` +
+          `directly in this file (or its sibling phase file). If you intended a different module helper, ` +
+          `replace the path with one of: ${nearest.slice(0, 3).map(n => `\`${n.name}\``).join(', ') || '(none)'}. ` +
+          `Use \`module_info(${moduleName}, api)\` for the full list.`
+        : `Replace \`${name}\` with the closest valid export: ${nearest.slice(0, 3).map(n => `\`${n.name}\``).join(', ') || '(none)'}, ` +
+          `or call \`module_info(${moduleName}, api)\` to see every callable path the module exposes.`;
+
       return {
         rule_id: 'MissingPartial.module_path',
-        hint_md: `\`${name}\` is a module path — cannot create files inside installed modules. Use \`module_info\` to verify the correct path.`,
+        hint_md: hint,
         fixes: [{
           type: 'guidance',
-          description: `Cannot create files inside module \`${moduleName}\`. Call \`module_info("${moduleName}", "api")\` to find the correct partial path exported by this module.`,
+          description: fixDescription,
         }],
-        confidence: 0.9,
+        confidence: nearest.length > 0 ? 0.9 : 0.7,
         see_also: {
           tool: 'module_info',
           args: { name: moduleName, section: 'api' },
-          reason: `Module partial '${name}' not found. module_info(${moduleName}, api) returns live-scanned call paths from the installed module.`,
+          reason: `module_info(${moduleName}, api) returns live-scanned call paths and @param signatures for every export.`,
         },
       };
     },
@@ -145,3 +247,22 @@ export const rules = [
     },
   },
 ];
+
+/**
+ * Split `modules///` into its parts. The returned
+ * `category` is the literal first segment after the module name (callers
+ * decide whether it maps to a known module-export bucket); `rest` is the
+ * remainder joined with '/'. Returns nulls when the input doesn't fit the
+ * shape so callers can shortcut.
+ */
+export function parseModulePath(name) {
+  if (!name || !name.startsWith('modules/')) {
+    return { moduleName: null, category: null, rest: null };
+  }
+  const parts = name.split('/');
+  // parts[0] === 'modules'
+  const moduleName = parts[1] ?? null;
+  const category = parts[2] ?? null;
+  const rest = parts.length > 3 ? parts.slice(3).join('/') : null;
+  return { moduleName, category, rest };
+}
diff --git a/src/core/rules/MissingSlug.js b/src/core/rules/MissingSlug.js
new file mode 100644
index 0000000..58d7188
--- /dev/null
+++ b/src/core/rules/MissingSlug.js
@@ -0,0 +1,42 @@
+/**
+ * pos-supervisor:MissingSlug rule — pages without a `slug:` in their front
+ * matter. Pre-rule the check landed as `.unmatched` even though the
+ * fix-generator already produces an `insert` text_edit
+ * (`fixMissingSlugInsert`) that prefills a sensible slug from the file
+ * path. This rule promotes the check to a stable rule_id and ships a
+ * `guidance` fix that explains *why* the slug matters — the heuristic's
+ * literal text_edit remains the actionable diff.
+ */
+
+export const rules = [
+  {
+    id: 'MissingSlug.default',
+    check: 'pos-supervisor:MissingSlug',
+    priority: 100,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'MissingSlug.default',
+      hint_md:
+        'Page is missing `slug:` in its front matter. Without an explicit slug the platform falls back to ' +
+        'a path derived from the filename — fine for one-off pages, but unstable when the file is renamed ' +
+        'or moved. Set `slug:` explicitly so URLs are owned by the page, not the filesystem.\n\n' +
+        'Conventions:\n' +
+        '  • Use kebab-case and avoid the file extension (`slug: contact`, not `slug: contact.liquid`).\n' +
+        '  • Use `:param` for dynamic segments (`slug: posts/:id`), not `[param]` (Next.js style).\n' +
+        '  • No leading slash — `slug: foo`, not `slug: /foo`.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Add `slug: ` between the front matter `---` markers. ' +
+          'The heuristic fix-generator proposes a slug derived from the filename — accept it ' +
+          'unless the public URL should diverge from the path.',
+      }],
+      confidence: 0.85,
+      see_also: {
+        tool: 'domain_guide',
+        args: { domain: 'pages' },
+        reason: 'Pages domain guide describes slug conventions and how dynamic segments resolve.',
+      },
+    }),
+  },
+];
diff --git a/src/core/rules/NonGetRenderingPage.js b/src/core/rules/NonGetRenderingPage.js
index f6bd6fc..f79f1b1 100644
--- a/src/core/rules/NonGetRenderingPage.js
+++ b/src/core/rules/NonGetRenderingPage.js
@@ -1,26 +1,183 @@
 /**
- * NonGetRenderingPage rule — attribution + hint for pages whose method is
- * non-GET but whose body renders HTML. Emitted by structural-warnings.js;
- * this module gives the diagnostic a stable rule_id so it lands in Rule
- * Performance instead of `.unmatched`.
+ * NonGetRenderingPage rules — three distinct misconfigurations of page
+ * `method:` / `format:` / form `action` per the 2026-04-27 gist analysis
+ * (NonGetRenderingPageRule.md). The structural emitter
+ * (`validatePageMethodAndForms` in structural-warnings.js) is the only
+ * producer of `pos-supervisor:NonGetRenderingPage` and tags each emit with
+ * a leading-clause discriminator the rule layer routes by.
  *
- * The structural warning already produces a detailed message; the rule's
- * hint_md is intentionally shorter and action-oriented (decision tree).
- * No fix is proposed — the right answer depends on intent (landing page
- * vs API endpoint) and guessing would do more harm than good.
+ * Subrule analytics IDs:
+ *   • NonGetRenderingPage.api_renders_html  — API-pathed page (`/api/`,
+ *     `/_/`, `/internal/`) is non-GET but emits HTML or omits `format: json`.
+ *   • NonGetRenderingPage.html_on_post      — non-API page is non-GET but
+ *     renders HTML; browser GETs return 404.
+ *   • NonGetRenderingPage.get_form_target   — GET page hosts a
+ *     `` whose action is not under an
+ *     internal-API prefix and is not the page's own slug.
+ *   • NonGetRenderingPage.default           — fallback for diagnostics that
+ *     don't match any subrule discriminator (defensive — should not fire
+ *     in practice once the emitter is in sync with this router).
+ *
+ * Each subrule emits a concrete `guidance` fix that names the right shape
+ * to converge on. No `text_edit` here: the deterministic fix requires
+ * cross-file changes (edit page front matter AND add an API endpoint AND
+ * possibly rewrite the form attribute) which the rule layer can't compose
+ * safely. Agents accept the guidance, then validate iteratively.
  */
 
+const API_RENDERS_HTML_RE = /^API page \(slug `([^`]+)`\) has `method: (\w+)`/;
+const HTML_ON_POST_RE = /^Page has `method: (\w+)` but renders HTML/;
+const GET_FORM_TARGET_RE = /^Form on GET page posts to `([^`]+)`/;
+
 export const rules = [
+  {
+    id: 'NonGetRenderingPage.api_renders_html',
+    check: 'pos-supervisor:NonGetRenderingPage',
+    priority: 5,
+    when: (diag) => API_RENDERS_HTML_RE.test(diag.message ?? ''),
+    apply: (diag) => {
+      const m = diag.message.match(API_RENDERS_HTML_RE);
+      const slug = m?.[1] ?? '';
+      const method = m?.[2] ?? 'post';
+      return {
+        rule_id: 'NonGetRenderingPage.api_renders_html',
+        hint_md:
+          `API page \`${slug}\` is set to \`method: ${method}\` but is configured to render HTML — ` +
+          `either it carries a \`layout:\` / inline HTML, or it is missing \`format: json\`. ` +
+          `Pages under \`/api/\`, \`/_/\`, or \`/internal/\` must respond with JSON; rendering HTML to ` +
+          `a JSON-expecting client is a silent contract break.\n\n` +
+          `Canonical shape:\n` +
+          '```liquid\n' +
+          `---\n` +
+          `slug: ${slug.replace(/^\//, '')}\n` +
+          `method: ${method}\n` +
+          `format: json\n` +
+          `---\n` +
+          `{% graphql result = 'mutation_path', ...args %}\n` +
+          `{{ result | json }}\n` +
+          '```',
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Add \`format: json\` to the front matter, drop any \`layout:\` line, and replace the body ` +
+            `with a \`{% graphql %}\` call followed by \`{{ result | json }}\`. ` +
+            `Keep \`method: ${method}\` so the verb still matches the form / fetch caller.`,
+        }],
+        confidence: 0.9,
+        see_also: {
+          tool: 'domain_guide',
+          args: { domain: 'api-calls' },
+          reason: 'API endpoint conventions in platformOS — JSON format, GraphQL bodies, no layout.',
+        },
+      };
+    },
+  },
+
+  {
+    id: 'NonGetRenderingPage.html_on_post',
+    check: 'pos-supervisor:NonGetRenderingPage',
+    priority: 10,
+    when: (diag) => HTML_ON_POST_RE.test(diag.message ?? ''),
+    apply: (diag) => {
+      const m = diag.message.match(HTML_ON_POST_RE);
+      const method = m?.[1] ?? 'post';
+      return {
+        rule_id: 'NonGetRenderingPage.html_on_post',
+        hint_md:
+          `Page renders HTML but is set to \`method: ${method}\`. Browsers always issue GET — ` +
+          `every navigation to this URL will 404. Two valid shapes:\n\n` +
+          `**Landing / display page** — drop the \`method:\` field (or set \`method: get\`); have any ` +
+          `embedded form POST to a separate API endpoint:\n` +
+          '```liquid\n' +
+          `---\nslug: contact\n---\n` +
+          `\n  \n\n` +
+          '```\n' +
+          `**Form-handling endpoint** — rename the slug under \`/api/\` and switch to JSON output:\n` +
+          '```liquid\n' +
+          `---\nslug: api/contacts/create\nmethod: ${method}\nformat: json\n---\n` +
+          `{% graphql result = 'contacts/create', ...context.params.contact %}\n` +
+          `{{ result | json }}\n` +
+          '```',
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Decide intent: (a) **landing page** — remove \`method: ${method}\` from front matter; the ` +
+            `form on this page should action to an \`/api/...\` slug. (b) **API handler** — move the slug ` +
+            `under \`/api/\`, add \`format: json\`, replace the HTML body with a \`{% graphql %}\` call.`,
+        }],
+        confidence: 0.9,
+        see_also: {
+          tool: 'domain_guide',
+          args: { domain: 'pages' },
+          reason: 'Page method semantics — GET serves browsers, non-GET handles form / fetch payloads.',
+        },
+      };
+    },
+  },
+
+  {
+    id: 'NonGetRenderingPage.get_form_target',
+    check: 'pos-supervisor:NonGetRenderingPage',
+    priority: 15,
+    when: (diag) => GET_FORM_TARGET_RE.test(diag.message ?? ''),
+    apply: (diag) => {
+      const m = diag.message.match(GET_FORM_TARGET_RE);
+      const action = m?.[1] ?? '';
+      const stripped = action.replace(/^\/+/, '');
+      const apiAction = `/api/${stripped}`;
+      const apiPagePath = `app/views/pages/api/${stripped}.liquid`;
+      return {
+        rule_id: 'NonGetRenderingPage.get_form_target',
+        hint_md:
+          `\`
      \` on this GET page posts to \`${action}\`. That action target is not under an ` +
+          `internal-API prefix (\`/api/\`, \`/_/\`, \`/internal/\`) and isn't the page's own slug, ` +
+          `so the submission has nowhere valid to land — unless an explicit \`method: post\` page already ` +
+          `serves \`${action}\`. The canonical fix is to route the form through an API page:\n\n` +
+          `1. Update the form action: \`\`.\n` +
+          `2. Create the API page at \`${apiPagePath}\` with \`method: post\`, \`format: json\`, and a ` +
+          `\`{% graphql %}\` body.`,
+        fixes: [{
+          type: 'guidance',
+          description:
+            `Change the form action from \`${action}\` to \`${apiAction}\` and create ` +
+            `\`${apiPagePath}\` as a \`method: post\` / \`format: json\` page. ` +
+            `Alternative (only if you control \`${action}\` already): verify that \`${action}\` is served ` +
+            `by a page with \`method: post\` — if not, NonGetRenderingPage.html_on_post will fire there.`,
+        }],
+        confidence: 0.85,
+        see_also: {
+          tool: 'domain_guide',
+          args: { domain: 'forms' },
+          reason: 'Form submission patterns — actions must hit a page with the matching `method:` verb.',
+        },
+      };
+    },
+  },
+
   {
     id: 'NonGetRenderingPage.default',
     check: 'pos-supervisor:NonGetRenderingPage',
     priority: 100,
     when: () => true,
-    apply: () => ({
+    apply: (diag) => ({
       rule_id: 'NonGetRenderingPage.default',
-      hint_md: 'Page will 404 on browser navigation because `method: post` only responds to POST. Decide: **landing page?** remove `method` (defaults to `get`) and have the form POST to a command handler. **API endpoint?** keep `method: post` but move the slug under `/api/…` and return JSON (not HTML). See the `NonGetRenderingPage` knowledge entry for full examples.',
-      fixes: [],
-      confidence: 0.9,
+      hint_md:
+        `Page method or form-target configuration is off. Read the upstream message for specifics — ` +
+        `the canonical platformOS shapes are:\n` +
+        `  • UI page → \`method: get\` (or omit), HTML body, layout allowed.\n` +
+        `  • API endpoint → slug under \`/api/\`, \`method: post\`/etc., \`format: json\`, no layout, ` +
+        `body is \`{% graphql %}\` + \`{{ result | json }}\`.\n` +
+        `  • Forms on GET pages → \`action="/api/"\` so the POST lands on the API page.`,
+      fixes: [{
+        type: 'guidance',
+        description:
+          `Decide whether this page is a UI page (GET, HTML) or an API page (non-GET, JSON). ` +
+          `Convert front matter and body to match — see \`domain_guide(pages)\` for the canonical layouts.`,
+      }],
+      confidence: 0.6,
     }),
   },
 ];
+
+// Re-exported for tests + diagnostic-pipeline introspection.
+export const _internal = { API_RENDERS_HTML_RE, HTML_ON_POST_RE, GET_FORM_TARGET_RE };
diff --git a/src/core/rules/OrphanedPartial.js b/src/core/rules/OrphanedPartial.js
new file mode 100644
index 0000000..b16ccde
--- /dev/null
+++ b/src/core/rules/OrphanedPartial.js
@@ -0,0 +1,120 @@
+/**
+ * OrphanedPartial rule — partial files that aren't rendered by anything
+ * else in the project graph.
+ *
+ * Pre-rule the check landed as `.unmatched`. The diagnostic-pipeline already
+ * suppresses commands/queries (invoked via `function`, not `render`) and
+ * pending-plan files via `suppressOrphanedPartial` upstream of this rule, so
+ * by the time we see one it's a real orphan in `app/views/partials/`.
+ *
+ * Two distinct intents → two recommendations:
+ *   • The file is dead code → delete it (high-confidence delete_file fix when
+ *     `referencedBy(file)` is empty in the graph).
+ *   • The file is mid-development and the caller hasn't been written yet →
+ *     pass `pending_files=[…callerPath]` to validate_code, or just write the
+ *     caller now. The hint surfaces this option so agents don't blindly
+ *     delete in-progress work.
+ *
+ * No fix when `diag.file` is missing — without the path we can't tell which
+ * file to act on.
+ */
+
+import { dependentsOf, classifyFileType } from './queries.js';
+
+export const rules = [
+  {
+    id: 'OrphanedPartial.default',
+    check: 'OrphanedPartial',
+    priority: 100,
+    when: () => true,
+    apply: (diag, facts) => {
+      const file = diag.file ?? null;
+      const fileType = file ? classifyFileType(file) : 'unknown';
+      const callers = file && facts?.graph ? dependentsOf(facts.graph, file) : [];
+      const callerCount = callers.length;
+      const filenameSpan = file ? `\`${file}\`` : 'this partial';
+
+      // The diagnostic-pipeline's `suppressOrphanedPartial` already drops
+      // commands/queries — by the time we see one, it should be a real
+      // partial. Belt-and-suspenders: if a non-partial slips through, give
+      // a softer "verify caller graph" message instead of a delete proposal.
+      const isPartial = fileType === 'partial';
+      const isLayout = fileType === 'layout';
+
+      const fixes = [];
+      if (isPartial && callerCount === 0) {
+        fixes.push({
+          type: 'delete_file',
+          path: file,
+          description:
+            `Delete ${filenameSpan} — no other file in the project renders it. ` +
+            `Re-run validate_code first if you're mid-feature; pass ` +
+            `\`pending_files=["${file}"]\` (or the caller's path) to suppress this warning while you write the caller.`,
+        });
+      }
+      fixes.push({
+        type: 'guidance',
+        description: orphanGuidance(filenameSpan, isPartial, isLayout),
+      });
+
+      return {
+        rule_id: 'OrphanedPartial.default',
+        hint_md: orphanHint(filenameSpan, callerCount, isPartial, isLayout),
+        fixes,
+        confidence: isPartial && callerCount === 0 ? 0.85 : 0.6,
+      };
+    },
+  },
+];
+
+function orphanHint(filenameSpan, callerCount, isPartial, isLayout) {
+  if (isLayout) {
+    return (
+      `${filenameSpan} is a layout with no pages selecting it via \`layout: \`. ` +
+      `Either select it from a page (\`---\\nlayout: ${filenameSpan.replace(/`/g, '').replace(/.*\//, '').replace(/\.liquid$/, '')}\\n---\`) ` +
+      `or delete the layout if it's no longer needed. Pages without a \`layout:\` key ` +
+      `default to \`application.liquid\`.`
+    );
+  }
+  if (!isPartial) {
+    return (
+      `${filenameSpan} appears to be unreferenced, but the file isn't a regular partial — ` +
+      `verify caller graph manually with \`platformos_references\` before deleting. ` +
+      `Commands and queries are invoked via \`{% function %}\` and may not always show up as ` +
+      `dependencies in the rendering graph.`
+    );
+  }
+  const callerNote = callerCount === 0
+    ? 'No file in the project renders or includes it.'
+    : `Found ${callerCount} caller(s) outside the standard render graph — verify with \`platformos_references\`.`;
+  return (
+    `${filenameSpan} is an orphaned partial. ${callerNote}\n\n` +
+    `Two valid resolutions:\n` +
+    `  • **Dead code** — delete the file. Use the \`delete_file\` fix if you're certain nothing renders it.\n` +
+    `  • **Work in progress** — the caller hasn't been written yet. Either write the caller now ` +
+    `(then re-validate, the warning clears), or pass \`pending_files=[""]\` to ` +
+    `validate_code so the orphan is suppressed during the multi-file plan.\n\n` +
+    `Renaming the file (e.g. via scaffold output) is the third common cause — re-run ` +
+    `\`project_map\` to confirm callers point at the current name.`
+  );
+}
+
+function orphanGuidance(filenameSpan, isPartial, isLayout) {
+  if (isLayout) {
+    return (
+      `Either set \`layout: \` in a page's front matter to use ${filenameSpan}, or delete the file ` +
+      `if it's no longer needed. Pages without an explicit \`layout:\` use \`application.liquid\`.`
+    );
+  }
+  if (!isPartial) {
+    return (
+      `Run \`platformos_references\` to enumerate every file that references ${filenameSpan}. ` +
+      `Commands/queries invoked via \`{% function %}\` may be missed by the render-graph orphan check.`
+    );
+  }
+  return (
+    `Decide: (a) delete ${filenameSpan} if it's dead, (b) write the calling page/partial if work is in progress, ` +
+    `or (c) pass \`pending_files=[""]\` to validate_code while you scaffold the caller. ` +
+    `Run \`platformos_references\` to confirm no rendering graph entry points at it.`
+  );
+}
diff --git a/src/core/rules/ParserBlockingScript.js b/src/core/rules/ParserBlockingScript.js
new file mode 100644
index 0000000..54d4a52
--- /dev/null
+++ b/src/core/rules/ParserBlockingScript.js
@@ -0,0 +1,46 @@
+/**
+ * ParserBlockingScript rule — `` placed at the very end of `` — the legacy workaround. ' +
+        'Prefer `defer` for new code.\n\n' +
+        'Inline scripts (`` with no `src`) are unaffected by this check.',
+      fixes: [{
+        type: 'guidance',
+        description:
+          'Add `defer` to the opening `
-Logo
-```
-
-### User Uploads
-
-Uploads are dynamic files stored per-record.
-
-**Table Definition:**
-```yaml
-name: product
-properties:
-  - name: image
-    type: upload
-```
-
-**Form:**
-```liquid
-{% form %}
-  
-{% endform %}
-```
-
-**Displaying Uploads:**
-```liquid
-{% graphql product = 'get_product', id: id %}
-{{ product.record.properties.image.file_name }}
-```
-
-**Upload Properties:**
-
-| Property | Description |
-|----------|-------------|
-| `url` | Direct file URL |
-| `file_name` | Original filename |
-| `content_type` | MIME type |
-| `size` | File size in bytes |
-
-### Assets vs Uploads
-
-| Aspect | Assets | Uploads |
-|--------|--------|---------|
-| Location | `app/assets/` | Record properties |
-| Use Case | Static files (CSS, JS, logos) | Dynamic content |
-| Quantity | Thousands expected | Millions supported |
-| CDN | Yes | Yes |
-| Max Size | 2GB | 2GB |
-
-### Direct S3 Upload
-
-platformOS uses **direct S3 upload** - files go straight to AWS S3 without passing through the application server.
-
-**Advantages:**
-- **Speed** - No middleman, faster uploads
-- **Cost** - Less bandwidth and server load
-- **Security** - No file processing on app server
-- **Scalability** - Handle unlimited concurrent uploads
-- **Size** - Up to 5GB single file, 5TB multipart
-
-**Upload Flow:**
-```
-1. User selects file
-2. Browser requests signed S3 URL from platformOS
-3. Browser uploads directly to S3
-4. S3 returns success
-5. platformOS saves file reference to record
-```
-
-### Upload Configuration Options
-
-**Table Definition with Options:**
-```yaml
-name: product
-properties:
-  - name: image
-    type: upload
-    options:
-      public: true              # Public or private access
-      max_size: 5242880         # 5MB in bytes
-      versions:
-        - name: thumbnail
-          resize: '200x200>'    # Resize to fit 200x200
-        - name: medium
-          resize: '800x600>'
-      extensions:
-        - jpg
-        - png
-        - gif
-```
-
-### Upload Versions
-
-Automatically generate resized versions:
-
-```yaml
-properties:
-  - name: photo
-    type: upload
-    options:
-      versions:
-        - name: thumb
-          resize: '100x100#'    # Exact fit, may crop
-        - name: medium
-          resize: '300x300>'    # Fit within, no upscale
-        - name: large
-          resize: '800x800>'
-```
-
-**Access versions in Liquid:**
-```liquid
-{{ product.properties.photo.url }}           # Original
-{{ product.properties.photo.versions.thumb.url }}   # Thumbnail
-{{ product.properties.photo.versions.medium.url }}  # Medium
-```
-
-### Image Processing Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `resize: '100x100'` | Resize to dimensions | Fit within |
-| `resize: '100x100>'` | Resize only if larger | Downscale only |
-| `resize: '100x100<'` | Resize only if smaller | Upscale only |
-| `resize: '100x100#'` | Exact dimensions | May crop |
-| `resize: '100x100^'` | Minimum dimensions | May crop |
-
----
-
-## 16. Best Practices
-
-### Code Organization
-
-```
-app/
-├── views/
-│   ├── pages/           # Route handlers
-│   ├── layouts/         # Page wrappers
-│   └── partials/
-│       ├── components/  # UI components
-│       ├── forms/       # Form partials
-│       └── helpers/     # Utility partials
-├── forms/               # Form configurations
-├── graphql/             # Data queries
-│   ├── records/
-│   ├── users/
-│   └── system/
-└── schema/              # Table definitions
-```
-
-### Naming Conventions
-
-| Component | Convention | Example |
-|-----------|------------|---------|
-| Tables | snake_case | `blog_post` |
-| Properties | snake_case | `published_at` |
-| Pages | snake_case | `about_us.liquid` |
-| Partials | snake_case | `header.liquid` |
-| Forms | snake_case | `contact_form.liquid` |
-| GraphQL | snake_case | `get_blog_posts.graphql` |
-
-### Security Best Practices
-
-1. **Always use authorization policies** for protected routes
-2. **Validate all inputs** using form validations
-3. **Escape output** using Liquid's auto-escaping
-4. **Use HTTPS** for all production instances
-5. **Store secrets** in Partner Portal constants, not code
-6. **Sanitize user content** before displaying
-
-### Performance Best Practices
-
-1. **Use pagination** for all list queries
-2. **Load related records** in single GraphQL query
-3. **Use background jobs** for long operations
-4. **Cache expensive queries** using static cache
-5. **Optimize images** before uploading as assets
-6. **Minimize GraphQL response size** with specific field selection
-
-### Error Handling
-
-```liquid
-{% graphql result = 'create_record', name: name %}
-
-{% if result.record_create.errors %}
-  
      
-    {% for error in result.record_create.errors %}
-      
      {{ error.message }}
      
-    {% endfor %}
-  
      
-{% else %}
-  
      Success! ID: {{ result.record_create.id }}
      
-{% endif %}
-```
-
----
-
-## 17. Common Gotchas & Pitfalls
-
-### 1. Variable Scope in Background Jobs
-
-**WRONG:**
-```liquid
-{% assign user_id = context.current_user.id %}
-{% background %}
-  {{ user_id }}  {# nil - not passed #}
-{% endbackground %}
-```
-
-**CORRECT:**
-```liquid
-{% assign user_id = context.current_user.id %}
-{% background user_id: user_id %}
-  {{ user_id }}  {# Works! #}
-{% endbackground %}
-```
-
-### 2. N+1 Query Problem
-
-**WRONG (N+1 queries):**
-```liquid
-{% graphql companies = 'get_companies' %}
-{% for company in companies.records.results %}
-  {% graphql programmers = 'get_programmers', company_id: company.id %}
-  {# Each iteration = 1 query! #}
-{% endfor %}
-```
-
-**CORRECT (single query):**
-```graphql
-query get_companies_with_programmers {
-  records(
-    filter: { table: { value: "company" } }
-  ) {
-    results {
-      id
-      properties
-      programmers: related_records(
-        table: "programmer"
-        foreign_property: "company_id"
-      ) {
-        id
-        properties
-      }
-    }
-  }
-}
-```
-
-### 3. Form Field Name Format
-
-**WRONG:**
-```liquid
-  {# Won't bind to form #}
-```
-
-**CORRECT:**
-```liquid
-
-```
-
-### 4. Module File References
-
-**WRONG:**
-```liquid
-{% render 'modules/my_module/public/header' %}
-```
-
-**CORRECT:**
-```liquid
-{% render 'modules/my_module/header' %}
-```
-
-### 5. Date/Time Formatting
-
-**WRONG:**
-```liquid
-{{ '2024-01-01' | strftime: '%Y' }}  {# Error - not a time object #}
-```
-
-**CORRECT:**
-```liquid
-{{ '2024-01-01' | to_time | strftime: '%Y' }}
-```
-
-### 6. Array vs JSONB Confusion
-
-**Arrays** - for simple lists:
-```yaml
-type: array
-# Value: ["a", "b", "c"]
-```
-
-**JSONB** - for complex objects:
-```yaml
-type: jsonb
-# Value: {"nested": {"key": "value"}}
-```
-
-### 7. Form Resource Owner
-
-**For public forms** (contact, newsletter):
-```yaml
-resource_owner: anyone
-```
-
-**For authenticated forms** (profile edit):
-```yaml
-resource_owner: self
-```
-
-**For admin forms**:
-```yaml
-resource_owner: anyone_with_token
-authorization_policies:
-  - admin_only_policy
-```
-
-### 8. Whitespace in Liquid
-
-**Problem:** Extra whitespace in output
-```liquid
-{% if true %}
-  Content
-{% endif %}
-{# Outputs newlines around content #}
-```
-
-**Solution:** Use whitespace control
-```liquid
-{%- if true -%}
-  Content
-{%- endif -%}
-```
-
-### 9. GraphQL Variable Types
-
-**Integer vs Float:**
-```graphql
-# Integer property
-{ name: "count", value_int: 5 }
-
-# Float property  
-{ name: "price", value_float: 19.99 }
-```
-
-**Boolean:**
-```graphql
-{ name: "active", value_boolean: true }
-```
-
-### 10. Soft Delete vs Hard Delete
-
-**Soft delete** (default):
-```graphql
-mutation {
-  record_delete(id: "123") {
-    id
-    deleted_at  # Timestamp set
-  }
-}
-```
-
-**Hard delete** (permanent):
-```graphql
-mutation {
-  record_delete(id: "123", hard_delete: true) {
-    id
-  }
-}
-```
-
-### 11. Reserved Names
-
-Avoid these reserved names for custom tables and properties:
-
-**System Fields (automatically created):**
-- `id` - Record UUID
-- `created_at` - Creation timestamp
-- `updated_at` - Last update timestamp
-- `deleted_at` - Soft delete timestamp
-- `type_name` - Table name
-- `properties` - Property container
-
-**Reserved Words:**
-- `user`, `users` - Built-in User table
-- `session`, `sessions` - Session management
-- `record`, `records` - Record operations
-- `constant`, `constants` - System constants
-- `table`, `tables` - Table metadata
-
-### 12. Form Resource Owner Confusion
-
-| Value | When to Use |
-|-------|-------------|
-| `anyone` | Public forms (contact, newsletter) |
-| `self` | User editing their own data |
-| `anyone_with_token` | API endpoints with token auth |
-
-**Wrong:**
-```yaml
-resource_owner: self  # Won't work for public contact form
-```
-
-**Correct:**
-```yaml
-resource_owner: anyone  # For public forms
-```
-
-### 13. Module File Deletion Behavior
-
-By default, module files are **NOT deleted** during deploy to protect private files.
-
-To enable deletion for a module:
-```yaml
-# app/config.yml
-modules_that_allow_delete_on_deploy:
-  - my_module
-```
-
-### 14. GraphQL Query Caching
-
-GraphQL queries are cached by default. To bypass cache:
-```graphql
-query {
-  records(
-    per_page: 10
-    filter: { table: { value: "product" } }
-  ) @skip_cache {
-    results { id }
-  }
-}
-```
-
-### 15. File Upload Size Limits
-
-| Upload Type | Max Size |
-|-------------|----------|
-| Direct S3 (single part) | 5 GB |
-| Direct S3 (multipart) | 5 TB |
-| Application-processed | 2 GB |
-
-### 16. Background Job Payload Limits
-
-```liquid
-{# WRONG - payload too large #}
-{% background data: huge_array_with_thousands_of_items %}
-
-{# CORRECT - pass reference only #}
-{% background record_id: record_id %}
-  {% graphql record = 'get_record', id: record_id %}
-  {# Process data in background #}
-{% endbackground %}
-```
-
-### 17. Liquid Truthiness
-
-In Liquid, only `nil` and `false` are falsy. Empty strings and zero are truthy:
-
-```liquid
-{% if '' %}TRUE{% endif %}     {# TRUE! #}
-{% if 0 %}TRUE{% endif %}       {# TRUE! #}
-{% if empty_array %}TRUE{% endif %}  {# FALSE (nil) #}
-{% if false %}TRUE{% endif %}    {# FALSE #}
-```
-
-Use `blank` and `present` for better checks:
-```liquid
-{% if '' == blank %}EMPTY{% endif %}  {# EMPTY #}
-{% if 0 == blank %}ZERO IS BLANK{% endif %}  {# Not blank! #}
-```
-
----
-
-## 18. Performance Optimization
-
-### Measuring Performance
-
-**time_diff filter:**
-```liquid
-{% assign start = 'now' | to_time %}
-
-{% graphql posts = 'get_posts' %}
-
-{% assign duration = start | time_diff: 'now' %}
-
      Query took: {{ duration }}ms
      
-```
-
-### Query Optimization
-
-**1. Select only needed fields:**
-```graphql
-# BAD - fetches everything
-query {
-  records { results { properties } }
-}
-
-# GOOD - specific fields
-query {
-  records { 
-    results { 
-      id
-      properties
-    } 
-  }
-}
-```
-
-**2. Use pagination:**
-```graphql
-query {
-  records(per_page: 20, page: 1) {
-    total_entries
-    results { id }
-  }
-}
-```
-
-**3. Load related records efficiently:**
-```graphql
-query {
-  records(filter: { table: { value: "order" } }) {
-    results {
-      id
-      items: related_records(table: "order_item") {
-        id
-        properties
-      }
-    }
-  }
-}
-```
-
-### Caching Strategies
-
-**Static Cache (Edge Caching):**
-```liquid
----
-slug: public-page
-response_headers:
-  Cache-Control: public, max-age=3600
----
-```
-
-**Fragment Caching:**
-```liquid
-{% cache key: 'sidebar', expire: 3600 %}
-  {% graphql categories = 'get_categories' %}
-  {% for category in categories.records.results %}
-    {{ category.properties.name }}
-  {% endfor %}
-{% endcache %}
-```
-
-### Background Job Optimization
-
-**Keep payloads small:**
-```liquid
-{# BAD - large payload #}
-{% background data: huge_array %}
-
-{# GOOD - pass reference #}
-{% assign job_id = 'process_' | append: record_id %}
-{% background job_id: job_id, record_id: record_id %}
-  {% graphql record = 'get_record', id: record_id %}
-  {# Process in background #}
-{% endbackground %}
-```
-
----
-
-## 19. Testing & CI/CD
-
-### pos-cli GUI
-
-```bash
-# Start GUI for GraphQL development
-pos-cli gui serve staging
-
-# Access at http://localhost:3333
-```
-
-### platformOS Check
-
-```bash
-# Install
-npm install -g @platformos/platformos-check
-
-# Run checks
-platformos-check
-
-# Auto-fix issues
-platformos-check --auto-correct
-```
-
-### GitHub Actions CI
-
-**File:** `.github/workflows/platformos.yml`
-```yaml
-name: platformOS CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install pos-cli
-        run: npm install -g @platformos/pos-cli
-      
-      - name: Deploy to Staging
-        run: pos-cli deploy staging
-        env:
-          MPKIT_TOKEN: ${{ secrets.MPKIT_TOKEN }}
-          MPKIT_URL: ${{ secrets.STAGING_URL }}
-      
-      - name: Run Tests
-        run: npm test
-```
-
-### Release Pool Setup
-
-1. Create dedicated test instances in Partner Portal
-2. Configure GitHub secrets:
-   - `MPKIT_TOKEN`
-   - `STAGING_URL`
-   - `PRODUCTION_URL`
-
-### Testing Best Practices
-
-1. **Unit test** GraphQL queries
-2. **Integration test** form submissions
-3. **E2E test** critical user flows
-4. **Performance test** with realistic data volumes
-5. **Security test** authorization policies
-
----
-
-## 20. System Limitations
-
-### Resource Limits
-
-| Resource | Limit | Notes |
-|----------|-------|-------|
-| File upload size | 2GB | Assets and uploads |
-| Background job payload | 100KB | Keep payloads small |
-| Background job execution | 1-60 min | Depends on priority |
-| GraphQL query complexity | Varies | Monitor performance |
-| Records per query | Unlimited | Use pagination |
-| Assets | Thousands | Use uploads for dynamic content |
-| Uploads | Millions | No practical limit |
-
-### Background Job Limits
-
-| Priority | Max Execution | Use For |
-|----------|---------------|---------|
-| `high` | 1 minute | Critical, urgent tasks |
-| `default` | 5 minutes | Standard operations |
-| `low` | 60 minutes | Heavy processing |
-
-### Rate Limiting
-
-- API calls may be rate-limited based on plan
-- Background job scheduling has queue limits
-- GraphQL queries have complexity scoring
-
-### Reserved Names
-
-Avoid these names for custom tables/properties:
-- `id`, `created_at`, `updated_at`, `deleted_at`
-- `type_name`, `properties`, `user`
-- Built-in Liquid objects and filters
-
----
-
-## 22. Data Import/Export
-
-### Exporting Data
-
-```bash
-# Export all data from an instance
-pos-cli data export staging --path=./export.json
-
-# Export specific tables
-pos-cli data export staging --tables=products,orders --path=./products.json
-```
-
-### Importing Data
-
-```bash
-# Import data to an instance
-pos-cli data import staging ./export.json
-
-# Import with transformations
-pos-cli data import staging ./data.json --transform=./transform.js
-```
-
-### Data Export Format
-
-```json
-{
-  "users": [
-    {
-      "id": "123",
-      "email": "user@example.com",
-      "created_at": "2024-01-15T10:00:00Z",
-      "properties": {
-        "first_name": "John",
-        "last_name": "Doe"
-      }
-    }
-  ],
-  "records": {
-    "product": [
-      {
-        "id": "456",
-        "properties": {
-          "name": "Widget",
-          "price": 19.99
-        }
-      }
-    ]
-  }
-}
-```
-
-### Programmatic Import with Migrations
-
-```liquid
-{# app/migrations/20240115000000_import_products.liquid #}
-{% parse_json data %}
-  {{ 'data/products.json' | load_file }}
-{% endparse_json %}
-
-{% for product in data.products %}
-  {% graphql result = 'create_product',
-    name: product.name,
-    price: product.price,
-    sku: product.sku
-  %}
-  {% log result %}
-{% endfor %}
-```
-
-### Cleaning Instance Data
-
-```bash
-# WARNING: This deletes all data!
-pos-cli data clean staging
-
-# Clean specific tables
-pos-cli data clean staging --tables=products,orders
-```
-
----
-
-## 23. Quick Reference
-
-### File Templates
-
-**New Page:**
-```liquid
----
-slug: my-page
-layout: application
----
-
-
      Page Title
      
-```
-
-**New Table:**
-```yaml
-name: my_table
-properties:
-  - name: name
-    type: string
-```
-
-**New Form:**
-```liquid
----
-name: my_form
-resource: my_table
-resource_owner: anyone
-redirect_to: /success
-fields:
-  properties:
-    name:
-      validation:
-        presence: true
----
-
-{% form %}
-  
-  
-{% endform %}
-```
-
-**New GraphQL Query:**
-```graphql
-query my_query($param: String) {
-  records(filter: { table: { value: "my_table" } }) {
-    results { id properties }
-  }
-}
-```
-
-### Common Liquid Patterns
-
-**Conditional rendering:**
-```liquid
-{% if condition %}
-  
-{% elsif other_condition %}
-  
-{% else %}
-  
-{% endif %}
-```
-
-**Loop with index:**
-```liquid
-{% for item in items %}
-  {{ forloop.index }}: {{ item.name }}
-{% endfor %}
-```
-
-**Pagination:**
-```liquid
-{% if records.has_previous_page %}
-  Previous
-{% endif %}
-
-{% if records.has_next_page %}
-  Next
-{% endif %}
-```
-
-### Common GraphQL Patterns
-
-**Create with error handling:**
-```graphql
-mutation {
-  record_create(record: { table: "post", properties: [] }) {
-    id
-    errors { message }
-  }
-}
-```
-
-**Update specific fields:**
-```graphql
-mutation {
-  record_update(id: "123", record: { properties: [{ name: "status", value: "published" }] }) {
-    id
-    properties
-  }
-}
-```
-
-**Search with filters:**
-```graphql
-query {
-  records(
-    filter: {
-      table: { value: "product" }
-      properties: [{ name: "category", value: "electronics" }]
-      created_at: { gte: "2024-01-01" }
-    }
-  ) {
-    results { id }
-  }
-}
-```
-
-### pos-cli Commands
-
-```bash
-# Authentication
-pos-cli auth login                    # Login to Partner Portal
-
-# Development
-pos-cli sync staging                  # Watch and sync changes
-pos-cli deploy staging                # Deploy to instance
-pos-cli deploy staging -f             # Force deploy (delete missing files)
-
-# Data
-pos-cli data export staging           # Export instance data
-pos-cli data import staging file.json # Import data
-pos-cli migrations run staging        # Run pending migrations
-
-# Modules
-pos-cli modules install module_name   # Install module
-pos-cli modules remove module_name    # Remove module
-
-# GUI
-pos-cli gui serve staging             # Start development GUI
-
-# Logs
-pos-cli logs staging                  # Stream logs
-```
-
-### Error Messages Reference
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `Record not found` | Invalid ID | Check record exists |
-| `Validation failed` | Invalid data | Check form validations |
-| `Unauthorized` | Policy failed | Check authorization |
-| `Rate limited` | Too many requests | Add delays, use caching |
-| `Timeout` | Query too slow | Optimize query, add pagination |
-| `Property not found` | Wrong property name | Check table schema |
-| `Table not found` | Wrong table name | Check table definition |
-| `Form not found` | Wrong form name | Check form file exists |
-
-### GraphQL Property Type Mapping
-
-| Property Type | GraphQL Input | Example |
-|---------------|---------------|---------|
-| `string` | `value: "text"` | `{ name: "title", value: "Hello" }` |
-| `integer` | `value_int: 42` | `{ name: "count", value_int: 5 }` |
-| `float` | `value_float: 19.99` | `{ name: "price", value_float: 19.99 }` |
-| `boolean` | `value_boolean: true` | `{ name: "active", value_boolean: true }` |
-| `date` | `value: "2024-01-15"` | `{ name: "birthday", value: "2024-01-15" }` |
-| `datetime` | `value: "2024-01-15T10:00:00Z"` | ISO 8601 format |
-| `array` | `value_array: ["a", "b"]` | `{ name: "tags", value_array: ["a", "b"] }` |
-| `jsonb` | `value_json: "{}"` | JSON string |
-| `upload` | Via form only | File uploads |
-
-### Form Validation Reference
-
-| Validation | Syntax | Description |
-|------------|--------|-------------|
-| `presence` | `presence: true` | Required field |
-| `email` | `email: true` | Valid email format |
-| `uniqueness` | `uniqueness: true` | Must be unique |
-| `length` | `length: { minimum: 5, maximum: 100 }` | String length |
-| `numericality` | `numericality: { greater_than: 0 }` | Number range |
-| `confirmation` | `confirmation: true` | Must match confirmation field |
-| `url` | `url: true` | Valid URL format |
-
-### pos-cli Extended Commands
-
-```bash
-# Authentication
-pos-cli auth login                      # Login to Partner Portal
-pos-cli auth logout                     # Logout
-
-# Development
-pos-cli sync staging                    # Watch and sync changes
-pos-cli sync staging --live-reload      # With live reload
-pos-cli deploy staging                  # Deploy to instance
-pos-cli deploy staging -f               # Force deploy (delete missing files)
-pos-cli deploy staging --direct-assets  # Deploy assets directly
-
-# Data Management
-pos-cli data export staging             # Export all data
-pos-cli data export staging --tables=products,orders
-pos-cli data import staging file.json   # Import data
-pos-cli data clean staging              # Delete all data (DANGER!)
-pos-cli migrations run staging          # Run pending migrations
-pos-cli migrations status staging       # Check migration status
-
-# Modules
-pos-cli modules install module_name     # Install module
-pos-cli modules install module_name@1.2 # Specific version
-pos-cli modules remove module_name      # Remove module
-pos-cli modules list staging            # List installed modules
-
-# GUI Tools
-pos-cli gui serve staging               # Start development GUI
-pos-cli gui serve staging --port 3333   # Custom port
-
-# Logs
-pos-cli logs staging                    # Stream logs
-pos-cli logs staging --tail 100         # Last 100 lines
-pos-cli logs staging --follow           # Follow new logs
-
-# Environment
-pos-cli env list                        # List environments
-pos-cli env add production              # Add environment
-pos-cli env remove staging              # Remove environment
-
-# Testing
-pos-cli test staging                    # Run tests
-
-# Debug
-pos-cli shell staging                   # Interactive shell
-```
-
----
-
-## 24. Translations
-
-### Overview
-
-Translations serve three main purposes:
-1. **Multi-language sites** - Static copy in multiple languages
-2. **Date formatting** - Consistent date/time display
-3. **Flash messages** - System message localization
-
-### Translation Files
-
-**File:** `app/translations/en.yml`
-```yaml
-en:
-  hello: "Hello"
-  welcome: "Welcome to our site"
-  buttons:
-    submit: "Submit"
-    cancel: "Cancel"
-  errors:
-    not_found: "Page not found"
-```
-
-**File:** `app/translations/es.yml`
-```yaml
-es:
-  hello: "Hola"
-  welcome: "Bienvenido a nuestro sitio"
-  buttons:
-    submit: "Enviar"
-    cancel: "Cancelar"
-  errors:
-    not_found: "Página no encontrada"
-```
-
-### Using Translations in Liquid
-
-**Basic translation:**
-```liquid
-{{ 'hello' | t }}                    # Output: Hello (or Hola)
-```
-
-**Nested keys:**
-```liquid
-{{ 'buttons.submit' | t }}           # Output: Submit
-{{ 'errors.not_found' | t }}         # Output: Page not found
-```
-
-**With interpolation:**
-```yaml
-# en.yml
-welcome_user: "Welcome, {{ name }}!"
-```
-```liquid
-{{ 'welcome_user' | t: name: user.first_name }}
-```
-
-### Date Localization
-
-Use the `l` (localize) filter for consistent date formatting:
-
-```yaml
-# en.yml
-date:
-  formats:
-    short: "%b %d, %Y"
-    long: "%B %d, %Y %H:%M"
-```
-```liquid
-{{ 'now' | l: 'short' }}             # Jan 15, 2024
-{{ post.published_at | l: 'long' }}  # January 15, 2024 14:30
-```
-
-### Language Detection
-
-platformOS automatically detects language from:
-1. User's `language` property (if set)
-2. Browser's Accept-Language header
-3. Default language (English)
-
-Access current language:
-```liquid
-{{ context.language }}               # Current language code (e.g., "en")
-```
-
----
-
-## 25. Activity Feeds
-
-### Overview
-
-Activity Feeds implement the [W3C Activity Streams 2.0](https://www.w3.org/TR/2017/REC-activitystreams-core-20170523/) specification for tracking user activities.
-
-**Key Characteristics:**
-- Activities are **immutable** (append-only)
-- Each activity has a **unique UUID**
-- Activities can be shared between actors
-- Activities represent events that happened in the past
-
-### Activity Structure
-
-```json
-{
-  "actor": {
-    "type": "Person",
-    "id": "User.1",
-    "name": "Sally Smith"
-  },
-  "type": "Create",
-  "object": {
-    "type": "Relationship",
-    "id": "Relationship.42"
-  },
-  "target": {
-    "type": "Group",
-    "id": "Group.5"
-  }
-}
-```
-
-### Creating Activities
-
-**GraphQL Mutation:**
-```graphql
-mutation create_activity {
-  activity_create(
-    activity: {
-      type: "Join"
-      actor: {
-        type: "Person"
-        id: "User.123"
-        name: "John Doe"
-      }
-      object: {
-        type: "Group"
-        id: "Group.456"
-      }
-    }
-  ) {
-    id
-    uuid
-  }
-}
-```
-
-### Publishing to Feeds
-
-After creating an activity, publish it to feeds:
-
-```graphql
-mutation publish_to_feed {
-  feed_publish(
-    feed_id: "user_123_notifications"
-    activity_uuid: "abc-123-uuid"
-  ) {
-    id
-  }
-}
-```
-
-### Querying Feeds
-
-```graphql
-query get_user_feed {
-  feeds(
-    feed_id: "user_123_notifications"
-    per_page: 20
-  ) {
-    total_entries
-    results {
-      id
-      uuid
-      type
-      actor
-      object
-      target
-      created_at
-    }
-  }
-}
-```
-
-### Common Activity Types
-
-| Type | Description |
-|------|-------------|
-| `Create` | Created something |
-| `Update` | Updated something |
-| `Delete` | Deleted something |
-| `Join` | Joined a group/event |
-| `Leave` | Left a group/event |
-| `Follow` | Started following |
-| `Like` | Liked content |
-| `Comment` | Commented on content |
-| `Share` | Shared content |
-| `Approve` | Approved a request |
-
----
-
-## 26. JSON Documents
-
-### Overview
-
-JSON Documents provide a schemaless data storage option for flexible, document-based data. Unlike Records (which require a Table schema), JSON Documents can store any valid JSON structure.
-
-**Use Cases:**
-- Configuration data
-- Unstructured content
-- Temporary data storage
-- Data that doesn't fit a rigid schema
-
-### Creating JSON Documents
-
-**GraphQL Mutation:**
-```graphql
-mutation create_json_document {
-  json_document_create(
-    document: {
-      name: "site_config"
-      content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}"
-    }
-  ) {
-    id
-    name
-    content
-    created_at
-  }
-}
-```
-
-### Querying JSON Documents
-
-```graphql
-query get_json_document {
-  json_document(name: "site_config") {
-    id
-    name
-    content
-    created_at
-    updated_at
-  }
-}
-
-query list_json_documents {
-  json_documents(
-    per_page: 10
-    sort: [{ created_at: { order: DESC } }]
-  ) {
-    results {
-      id
-      name
-      content
-    }
-  }
-}
-```
-
-### Updating JSON Documents
-
-```graphql
-mutation update_json_document {
-  json_document_update(
-    name: "site_config"
-    document: {
-      content: "{\"theme\": \"light\", \"features\": [\"blog\", \"shop\", \"forum\"]}"
-    }
-  ) {
-    id
-    content
-    updated_at
-  }
-}
-```
-
-### Using in Liquid
-
-```liquid
-{% graphql config = 'get_json_document', name: 'site_config' %}
-{% assign settings = config.json_document.content | parse_json %}
-
-Theme: {{ settings.theme }}
-Features: {{ settings.features | join: ', ' }}
-```
-
-### JSON Document vs Records
-
-| Feature | JSON Documents | Records |
-|---------|---------------|---------|
-| Schema | Schemaless | Defined in Table YAML |
-| Validation | None | Form validation |
-| Structure | Any JSON | Fixed properties |
-| Use Case | Config, flexible data | Structured entities |
-| GraphQL | `json_document_*` | `record_*` |
-
----
-
-## 27. AI Embeddings
-
-### Overview
-
-platformOS supports AI embeddings for semantic search and similarity matching. Embeddings are vector representations of text that capture semantic meaning.
-
-**Use Cases:**
-- Semantic search
-- Content recommendation
-- Similarity matching
-- Clustering
-
-### Creating Embeddings
-
-**GraphQL Mutation:**
-```graphql
-mutation create_embedding {
-  embedding_create(
-    embedding: {
-      name: "product_description"
-      value: "High-quality wireless headphones with noise cancellation"
-      target_id: "product_123"
-      target_type: "Product"
-    }
-  ) {
-    id
-    vector
-  }
-}
-```
-
-### Semantic Search
-
-```graphql
-query semantic_search {
-  embeddings_search(
-    query: "wireless audio devices"
-    limit: 10
-    threshold: 0.7
-  ) {
-    results {
-      id
-      target_id
-      target_type
-      similarity
-      value
-    }
-  }
-}
-```
-
-### Querying Embeddings
-
-```graphql
-query get_embedding {
-  embedding(
-    target_id: "product_123"
-    target_type: "Product"
-  ) {
-    id
-    name
-    value
-    vector
-    created_at
-  }
-}
-```
-
-### Deleting Embeddings
-
-```graphql
-mutation delete_embedding {
-  embedding_delete(
-    target_id: "product_123"
-    target_type: "Product"
-  ) {
-    id
-  }
-}
-```
-
-### Embedding Parameters
-
-| Parameter | Description |
-|-----------|-------------|
-| `name` | Identifier for the embedding type |
-| `value` | The text to embed |
-| `target_id` | ID of the associated entity |
-| `target_type` | Type of the associated entity |
-| `vector` | The computed embedding vector (read-only) |
-
----
-
-## 28. Migrations
-
-### Overview
-
-Migrations are Liquid scripts that run once to transform data. They are useful for:
-- Data transformations during schema changes
-- Bulk data updates
-- One-time data imports
-
-### Creating Migrations
-
-**File:** `app/migrations/20240115120000_add_status_to_products.liquid`
-```liquid
-{% graphql products = 'get_all_products' %}
-
-{% for product in products.records.results %}
-  {% graphql result = 'update_product_status', 
-    id: product.id, 
-    status: 'active' 
-  %}
-  {% log result %}
-{% endfor %}
-```
-
-### Migration File Naming
-
-Migrations are executed in alphabetical order. Use timestamps as prefixes:
-```
-app/migrations/
-├── 20240101000000_initial_setup.liquid
-├── 20240115120000_add_status.liquid
-└── 20240201000000_migrate_images.liquid
-```
-
-### Running Migrations
-
-```bash
-# Run pending migrations
-pos-cli migrations run staging
-
-# Check migration status
-pos-cli migrations status staging
-```
-
-### Migration Best Practices
-
-1. **Make migrations idempotent** - Running twice should not cause errors:
-```liquid
-{% graphql product = 'get_product', id: product_id %}
-{% unless product.record.properties.status %}
-  {# Only update if status is not set #}
-  {% graphql result = 'update_product', id: product_id, status: 'active' %}
-{% endunless %}
-```
-
-2. **Use background jobs for large migrations:**
-```liquid
-{% background source_name: 'data_migration' %}
-  {% graphql records = 'get_all_records' %}
-  {% for record in records.records.results %}
-    {# Process each record #}
-  {% endfor %}
-{% endbackground %}
-```
-
-3. **Test migrations on staging first**
-4. **Log progress for debugging:**
-```liquid
-{% log 'Migration started' %}
-{% log 'Processed ' | append: count | append: ' records' %}
-```
-
-### Migration Limitations
-
-- Migrations run as background jobs
-- Should complete within a few minutes
-- For long-running operations, use low-priority background jobs
-- Failed migrations can be retried
-
----
-
-## Resources
-
-- **Documentation:** https://documentation.platformos.com/
-- **API Reference:** https://documentation.platformos.com/api-reference
-- **Examples:** https://examples.platform-os.com/
-- **GitHub:** https://github.com/Platform-OS
-- **Partner Portal:** https://partners.platformos.com/
-- **Community:** https://community.platformos.com/
-
----
-
-*This guide is designed for LLM agents developing on platformOS. For the most up-to-date information, always refer to the official documentation.*
diff --git a/src/data/resources/platformos-development-guide.md b/src/data/resources/platformos-development-guide.md
index 21c47a3..4317191 100644
--- a/src/data/resources/platformos-development-guide.md
+++ b/src/data/resources/platformos-development-guide.md
@@ -1,257 +1,194 @@
-# platformOS Development Guide
-
-Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory
-workflow — read it before touching any file.
-
-## 0. MANDATORY WORKFLOW — Read Before Writing Any Code
-
-**You are STRICTLY FORBIDDEN from skipping this workflow**
-
-You MUST follow this loop for every feature. Each step produces structured output
-the next step consumes — skipping any step produces invalid state that downstream
-tools will reject.
-
-1. **`project_map`** — understand what already exists. MUST be called once per session
-   before any scaffold or write.
-2. **`scaffold(type, name, properties, write: false)`** — generate the authoritative
-   file set from platformOS-native templates. MUST use scaffold whenever a file set
-   matches one of its types (crud, api, command, query, partial, page).
-3. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files.
-   Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains
-   rules that are NOT in your training data and that differ from Shopify, Rails, and
-   generic Liquid.
-4. **`validate_intent` — declare your plan before touching disk.**
-   Two modes, pick by what you're doing next:
-
-   - **Mode A — hand-drafted batch (REQUIRED before manual writes).**
-     Call `validate_intent({ intent: { goal, changes: [...] } })` where
-     `changes` is an array of `{ path, role, action, references? }` — one
-     entry per file you intend to author. The plan is the contract for the
-     rest of the session.
-   - **Mode B — scaffold review (OPTIONAL).**
-     Call `validate_intent({ scaffold_output:  })`
-     only if you want a second look at the generated set before committing.
-     The default scaffold path skips this step.
-
-   **Read the response:**
-   - `ok: false` → fix `errors[].suggestion`, re-call. MUST NOT proceed.
-   - `ok: true` + `write_directly: true` → Mode B; go straight to
-     `scaffold(..., write: true)`.
-   - `ok: true` + `write_directly: false` → Mode A; draft each file, call
-     `validate_code` on the full content, then write.
-
-   **What `pending_files` / `pending_translations` / `pending_pages` are for:**
-   you can ignore them. The supervisor stores them and uses them to suppress
-   false-positive `MissingPartial` / `TranslationKeyExists` errors in later
-   `validate_code` / `analyze_project` calls — because those files are
-   *promised* by the plan but not on disk yet. You do not pass them to any
-   subsequent tool; the server merges them automatically.
-
-   **Skipping Mode A before hand-drafted writes** is the #1 cause of phantom
-   cross-reference errors: `validate_code` will flag every partial and
-   translation key the plan hasn't written yet, and the agent chases those
-   ghosts by deleting the references the plan needs.
-
-   **Scope drift:** if you add, rename, or drop a file that isn't in the
-   current `changes` array, re-call `validate_intent` with the updated plan
-   before writing the new file.
-
-5. **`scaffold(..., write: true)`** — writes all files to disk. If you went
-   through Mode B in step 4, this runs after `write_directly: true`.
-   Otherwise this is the direct follow-up to step 2. For hand-drafted edits
-   (Mode A, or manual edits without scaffold), call `validate_code` per file
-   and only write when validation passes — never rely on scaffold to write a
-   hand-authored file.
-6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or
-   `must_fix_before_write: true`, fix every error and re-validate. MUST NOT
-   write the file to disk until validation passes.
-   When debugging existing files, always read them from disk first and submit
-   their actual content to `validat_code` tool.
-7. Creation order matters: schema → graphql → partial → page.
-8. **`analyze_project` — project-wide health check.** MUST be called:
-   - **Before reporting task completion.** `validate_code` only sees one
-     file at a time; cross-file damage (broken render targets, orphaned
-     partials, dangling translations, schema drift) only surfaces from the
-     whole-project view. A task is not done until `analyze_project` returns
-     zero new errors or warnings introduced by this session.
-   - **When you feel lost.** If validate_code keeps reporting errors you
-     don't understand, if the same check keeps re-appearing after you
-     "fixed" it, if you suspect a file you edited affected callers you
-     can't see, or if `project_map` no longer matches your mental model —
-     stop editing and call `analyze_project` to re-ground. It returns
-     per-file error counts, the dependency graph, orphaned files, broken
-     references, and schema issues for every file in `app/`. That is the
-     authoritative picture of the project right now.
-
-   `analyze_project` respects `session.pending` — files declared in a
-   validated plan are not flagged as missing. You do not need to pass any
-   parameters for the standard case; omit `files` to analyze the whole
-   project.
-
-   MUST NOT: skip this step before announcing "done" just because
-   `validate_code` passed on the files you edited. Individual-file green
-   lights do not imply project integrity.
-
-
-### MUST-CALL domains (by feature type)
-
-- **Auth code** — `domain_guide(domain: "authentication")`
-- **Any form** — `domain_guide(domain: "forms")`
-- **New pages** — `domain_guide(domain: "pages")`
-- **New partials** — `domain_guide(domain: "partials")`
-- **GraphQL ops** — `domain_guide(domain: "graphql")`
-- **Any new domain** — `domain_guide(domain: "", section: "gotchas")`
-
-### MUST NOT
-
-- Use `{% include %}` for app code — deprecated. Use `{% render %}` or
-  `{% function %}`.
-- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These
-  do not exist in platformOS.
-- Write hand-drafted files to disk without calling `validate_code` on the proposed
-  content first. (Scaffold-written files are exempt — they are pre-validated.)
-- Assume module call syntax from memory — call `module_info(name)` to get the
-  authoritative live-scan API surface.
-- Ignore `consult_before_writing` in a scaffold response. Every domain listed there
-  MUST be consulted via `domain_guide` before writing.
-
-### Session-start checklist
-
-Before your first tool call, the following are true:
-
-- [ ] `server_status` called — confirms LSP and indexes are ready, lists
-  `domain_guides` and `session_pending`.
-- [ ] `load_development_guide` called (this document) — re-read if you lose
-  context or are unsure which step comes next.
-- [ ] `project_map` called once for full project baseline.
-
-Proceed only when all three are checked.
-
-## 1. Technology Stack
-
-platformOS uses three primary technologies:
-- **Liquid** — server-side templating language
-- **GraphQL** — data operations (built-in queries/mutations only)
-- **YAML** — configuration for schemas, translations, and settings
-
-The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access.
-
-platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag.
-
-### Source of Truth
-
-The official platformOS documentation is the ONLY source of truth:
-
-| Resource | URL |
-|----------|-----|
-| Official Docs | documentation.platformos.com |
-| GraphQL Schema | documentation.platformos.com/api/graphql/schema |
-| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md |
-| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md |
-| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md |
-| Core Module | github.com/Platform-OS/pos-module-core (README) |
-| User Module | github.com/Platform-OS/pos-module-user (README) |
-| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) |
-| Payments Module | github.com/Platform-OS/pos-module-payments (README) |
-| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) |
-| Tests Module | github.com/Platform-OS/pos-module-tests (README) |
-| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md |
-
-You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation.
+# platformOS Development Guide for LLM Agents
+
+> **Essential Knowledge Base for AI Coding Agents**  
+> Version: 2025-2026 | Last Updated: April 2026  
+> Source: [platformOS Documentation](https://documentation.platformos.com/)
+
+---
+
+## Table of Contents
+
+1. [Introduction & Architecture](#1-introduction--architecture)
+2. [Directory Structure](#2-directory-structure)
+3. [Core Concepts](#3-core-concepts)
+4. [Pages & Layouts](#4-pages--layouts)
+5. [Records & Tables](#5-records--tables)
+6. [Properties](#6-properties)
+7. [Forms](#7-forms)
+8. [Liquid Templating](#8-liquid-templating)
+9. [GraphQL API](#9-graphql-api)
+10. [Users & Authentication](#10-users--authentication)
+11. [Authorization Policies](#11-authorization-policies)
+12. [Modules](#12-modules)
+13. [Background Jobs](#13-background-jobs)
+14. [Notifications](#14-notifications)
+15. [Assets & Uploads](#15-assets--uploads)
+16. [Best Practices](#16-best-practices)
+17. [Common Gotchas & Pitfalls](#17-common-gotchas--pitfalls)
+18. [Performance Optimization](#18-performance-optimization)
+19. [Testing & CI/CD](#19-testing--cicd)
+20. [System Limitations](#20-system-limitations)
+21. [Data Import/Export](#22-data-importexport)
+22. [Quick Reference](#23-quick-reference)
+23. [Translations](#24-translations)
+24. [Activity Feeds](#25-activity-feeds)
+25. [JSON Documents](#26-json-documents)
+26. [AI Embeddings](#27-ai-embeddings)
+27. [Migrations](#28-migrations)
+
+---
+
+## 1. Introduction & Architecture
+
+### What is platformOS?
+
+platformOS is a **model-based application development platform** (PaaS) that enables developers to build web applications, APIs, and digital products without managing infrastructure. It combines:
+
+- **Liquid templating** for views
+- **GraphQL** for data queries and mutations
+- **YAML configuration** for schema definition
+- **Background job processing** for async operations
+- **Built-in authentication & authorization**
+
+### Key Architectural Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Convention over Configuration** | File locations determine behavior |
+| **Git-based Workflow** | Version control everything |
+| **Multi-tenancy** | Multiple instances per codebase |
+| **Serverless Backend** | No server management required |
+| **Edge Caching** | Built-in CDN for performance |
+
+### Development Workflow
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Local     │───▶│    Test     │───▶│   Staging   │───▶│  Production │
+│ Development │    │   Instance  │    │   Instance  │    │   Instance  │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+       │                  │                  │                  │
+       └──────────────────┴──────────────────┴──────────────────┘
+                              pos-cli deploy
+```
 
 ---
 
 ## 2. Directory Structure
 
+### Required Directory Layout
+
 ```
 project-root/
-├── app/
-│   ├── assets/                    # Static files (images, fonts, styles, scripts)
+├── app/                          # Main application code
+│   ├── assets/                   # Static files (CSS, JS, images)
+│   ├── authorization_policies/   # Access control rules
+│   ├── emails/                   # Email notification templates
+│   ├── api_calls/                # API call notifications
+│   ├── smses/                    # SMS notification templates
+│   ├── forms/                    # Form configurations
+│   ├── graphql/                  # GraphQL query files
+│   ├── migrations/               # Data migration scripts
+│   ├── schema/                   # Table definitions (YAML)
 │   ├── views/
-│   │   ├── pages/                 # Controllers — NO HTML here
-│   │   ├── layouts/               # Wrapper templates
-│   │   └── partials/              # Reusable template snippets
-│   ├── lib/
-│   │   ├── commands/              # Business logic (build → check → execute)
-│   │   ├── queries/               # Data retrieval wrappers
-│   │   ├── events/                # Event definitions
-│   │   └── consumers/             # Event handlers
-│   ├── schema/                    # Database table definitions (YAML)
-│   ├── graphql/                   # GraphQL query/mutation files
-│   ├── emails/                    # Email templates
-│   ├── smses/                     # SMS templates
-│   ├── api_calls/                 # Third-party API integrations
-│   ├── translations/              # i18n content (YAML)
-│   ├── authorization_policies/    # DO NOT USE — use pos-module-user
-│   ├── migrations/                # One-time migration scripts
-│   └── config.yml                 # Feature flags
-├── modules/                       # Downloaded/custom modules (READ-ONLY)
-└── .pos                           # Environment endpoints
-```
-
-All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`.
-
-The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only.
-
-### File Naming Conventions
-
-| Directory | Pattern | Example |
-|-----------|---------|---------|
-| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` |
-| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` |
-| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` |
-| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` |
-| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` |
-| Assets | `app/assets//` | `app/assets/images/logo.png` |
-| Translations | `app/translations/.yml` | `app/translations/en.yml` |
-
-### File Formats
-
-| Extension | Content-Type | URL |
-|-----------|--------------|-----|
-| `*.liquid` or `*.html.liquid` | `text/html` | `/path` |
-| `*.json.liquid` | `application/json` | `/path.json` |
-| `*.js.liquid` | `application/javascript` | `/path.js` |
+│   │   ├── layouts/              # Page layouts
+│   │   ├── pages/                # Page definitions
+│   │   └── partials/             # Reusable Liquid snippets
+│   ├── config.yml                # App configuration
+│   └── user.yml                  # User property definitions
+├── modules/                      # External modules
+│   └── MODULE_NAME/
+│       ├── public/               # Publicly accessible files
+│       └── private/              # IP-protected files
+└── .pos                          # pos-cli configuration
+```
 
----
+### Critical File Locations
 
-## 3. Architecture Rules
+| Component | Required Path | Extension |
+|-----------|---------------|-----------|
+| Pages | `app/views/pages/` | `.liquid` |
+| Layouts | `app/views/layouts/` | `.liquid` |
+| Partials | `app/views/partials/` | `.liquid` |
+| Tables | `app/schema/` | `.yml` |
+| Forms | `app/forms/` | `.liquid` |
+| GraphQL | `app/graphql/` | `.graphql` |
+| Assets | `app/assets/` | any |
 
-### Pages MUST Be Controllers
+### Configuration Files
 
-Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method.
+**`.pos` (pos-cli config):**
+```yaml
+staging:
+  url: https://staging.example.com
+  email: dev@example.com
+production:
+  url: https://www.example.com
+  email: dev@example.com
+```
+
+**`app/config.yml`:**
+```yaml
+# Modules that can be deleted during deploy
+modules_that_allow_delete_on_deploy:
+  - my_module
 
-### Business Logic MUST Live in Commands
+# Other app-level configuration
+```
 
-All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build → check → execute pattern.
+---
 
-### Path Resolution
+## 3. Core Concepts
 
-- `{% render 'blog_posts/card' %}` → `app/views/partials/blog_posts/card.liquid`
-- `{% function r = 'commands/blog_posts/create' %}` → `app/lib/commands/blog_posts/create.liquid`
-- `{% function r = 'queries/blog_posts/search' %}` → `app/lib/queries/blog_posts/search.liquid`
+### The platformOS Data Flow
 
-The `lib/` prefix is implicit in `function` calls — do NOT include it.
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│  Client  │───▶│  Router  │───▶│  Liquid  │───▶│ GraphQL  │
+│ Request  │    │  (Page)  │    │ Template │    │  Query   │
+└──────────┘    └──────────┘    └──────────┘    └────┬─────┘
+                                                     │
+                                                ┌────▼─────┐
+                                                │ Database │
+                                                │ (Record) │
+                                                └──────────┘
+```
 
-### Separation of Concerns
+### Key Terminology
 
-- UI (Liquid templates) MUST be in partials and layouts
-- Data operations (GraphQL) MUST be in query/mutation files
-- Logic (commands) MUST be in `app/lib/commands/`
+| Term | Definition |
+|------|------------|
+| **Instance** | A deployed environment (staging, production) |
+| **Table** | Schema definition for data objects |
+| **Record** | Individual data object instance |
+| **Property** | Field/column definition |
+| **Page** | Route handler + view template |
+| **Layout** | Wrapper template for pages |
+| **Partial** | Reusable template snippet |
+| **Form** | Configuration for data submission |
+| **Authorization Policy** | Access control rule |
 
-### Modules First
+---
 
-Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic.
+## 4. Pages & Layouts
 
-### Generators First (DEPRECATED — DO NOT USE)
+### Page Configuration
 
-You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available.
+Pages are defined in `app/views/pages/` with `.liquid` extension. URL path is derived from file location unless `slug` is specified.
 
+**File:** `app/views/pages/blog/post.html.liquid`
+```liquid
+---
+slug: blog/:slug
+layout: blog_layout
+converter: markdown
+authorization_policies:
+  - valid_user_policy
 ---
 
-## 4. Pages
-
-Pages are controllers — they handle routing, fetch data, and delegate to partials.
+
      {{ context.params.slug }}
      
+
      Author: {{ context.current_user.email }}
      
+```
 
 ### Front Matter
 
@@ -265,6 +202,17 @@ metadata:
 ---
 ```
 
+### Front Matter: Page Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `slug` | String | URL pattern (e.g., `products/:id`) |
+| `layout` | String | Layout template name |
+| `converter` | String | `markdown`, `textile` |
+| `authorization_policies` | Array | Policies to check |
+| `response_headers` | Hash | Custom HTTP headers |
+| `method` | String | HTTP method restriction |
+
 | Property | Default | Notes |
 |----------|---------|-------|
 | `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` |
@@ -272,808 +220,2958 @@ metadata:
 | `layout` | `application` | Empty string for no layout |
 
 **You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead.**
-**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.**
+**For the home page (root /), omit the slug entirely — `app/views/pages/index.liquid` serves `/` by default. WRONG: `slig: index`**
 **For the home page omit method as it can only be `get` which is default.**
 **One REST method per page**
 
-### Dynamic Routes
-
-| Pattern | URL | `context.params` |
-|---------|-----|------------------|
-| `products/:id` | `/products/123` | `{ "id": "123" }` |
-| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` |
-| `search(/:q)` | `/search/books` | `{ "q": "books" }` |
-
-### REST CRUD Convention
-
-| HTTP Method | URL Slug | Page File | GraphQL | Purpose |
-|-------------|----------|-----------|---------|---------|
-| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form |
-| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource |
-| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource |
-| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form |
-| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource |
-| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource |
-| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources |
-
-### CSRF Protection
-
-Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous).
+### Dynamic URL Parameters
 
-### GET Page Example
+```yaml
+# Required parameter
+slug: products/:id
+# Access: context.params.id
 
-```liquid
----
-slug: articles/:id
-method: get
----
-{% liquid
-  function article = 'queries/articles/find', id: context.params.id
+# Optional parameter
+slug: search(/:country)(/:city)
+# Matches: /search, /search/USA, /search/USA/NYC
 
-  if article == blank
-    render '404'
-    break
-  endif
+# Wildcard parameter
+slug: docs/*path
+# Access: context.params.path (contains full remaining path)
 
-  render 'articles/show', article: article
-%}
+# Optional wildcard
+slug: docs(/*path)
+# Matches: /docs and /docs/anything/here
 ```
 
-### POST Page Example
+### Layouts
 
+**File:** `app/views/layouts/application.liquid`
 ```liquid
----
-slug: articles
-method: post
----
-{% liquid
-  function result = 'commands/articles/create', object: context.params.article
-
-  if result.valid
-    function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname
-    redirect_to '/articles'
-  else
-    render 'articles/new', result: result
-  endif
-%}
+
+
+
+  {{ page_title | default: 'My App' }}
+  {{ content_for_head }}
+
+
+  {% render 'header' %}
+  
+  
      
+    {{ content_for_layout }}
+  
      
+  
+  {% render 'footer' %}
+
+
 ```
 
----
-
-## 5. Partials & Layouts
-
-### Partials
-
-Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`).
-
-Partials MUST NOT have underscore-prefixed filenames.
-
-The render path maps: `render 'path/name'` → `app/views/partials/path/name.liquid`.
-
-### Layouts
-
-The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout.
-
----
+**Key Layout Variables:**
+- `content_for_layout` - Page content injection point
+- `content_for_head` - Head content (meta tags, styles)
 
-## 6. Commands (Business Logic)
+### Context Object (Complete Reference)
 
-All business logic MUST be encapsulated in commands following the build → check → execute pattern.
+The `context` object is the **only predefined global object** in platformOS Liquid. It is available in pages, partials, layouts, and notifications.
 
-### Main Command
+#### Authentication & User
 
 ```liquid
-{% doc %}
-  @param object {object} - Article data
-{% enddoc %}
-
-{% liquid
-  function object = 'commands/articles/create/build', object: object
-  function object = 'commands/articles/create/check', object: object
-
-  if object.valid
-    function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object
-  endif
-
-  return object
-%}
+{{ context.current_user }}           # Current user object or null
+{{ context.current_user.id }}        # User UUID
+{{ context.current_user.email }}     # User email
+{{ context.current_user.first_name }}# First name
+{{ context.current_user.last_name }} # Last name
+{{ context.current_user.slug }}      # User slug
+{{ context.current_user.properties }}# Custom properties hash
 ```
 
-### Build Stage
-
-Normalizes and structures input data:
+#### Request Data
 
 ```liquid
-{% doc %}
-  @param object {object} - form params
-{% enddoc %}
-
-{% liquid
-  assign object['title'] = object.title
-  assign object['body'] = object.body
-
-  return object
-%}
+{{ context.params }}                 # URL params + query string + form data
+{{ context.params.id }}              # Named route parameter
+{{ context.params.page }}            # Query string parameter
+{{ context.headers }}                # HTTP headers hash
+{{ context.headers.REQUEST_METHOD }} # GET, POST, etc.
+{{ context.headers.PATH_INFO }}      # Request path
+{{ context.cookies }}                # Cookies hash
+{{ context.session }}                # Session data hash
 ```
 
-### Check Stage
-
-Validates the built object:
+#### Security
 
 ```liquid
-{% doc %}
-  @param object {object} - form params
-{% enddoc %}
-
-{% liquid
-  assign c = '{ "errors": {}, "valid": true }' | parse_json
-
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title'
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body'
-
-  assign object = object | hash_merge: valid: c.valid, errors: c.errors
+{{ context.authenticity_token }}     # CSRF token for forms
+{{ context.constants }}              # Sensitive config (API keys, secrets)
+```
 
-  return object
-%}
+**Accessing Constants:**
+```liquid
+{{ context.constants.STRIPE_API_KEY }}
+{{ context.constants.SENDGRID_API_KEY }}
 ```
 
-### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE)
+Set constants via GraphQL:
+```graphql
+mutation {
+  constant_set(name: "STRIPE_API_KEY", value: "sk_live_...")
+}
+```
 
-> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`).
+#### Device & Environment
 
 ```liquid
-{% comment %} WRONG — these partials do not exist: {% endcomment %}
-{% function object = 'modules/core/commands/build', object: object %}
-{% function object = 'modules/core/commands/check', object: object,
-  validators: '[{"name": "presence", "property": "title"}]'
-%}
-
-{% comment %} CORRECT — only execute is shared: {% endcomment %}
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
-    mutation_name: 'products/create', selection: 'record', object: object
-  %}
-{% endif %}
-
-{% return object %}
+{{ context.device }}                      # Device detection hash
+{{ context.device.device_type }}          # desktop, smartphone, tablet, etc.
+{{ context.device.browser }}              # Browser name
+{{ context.device.os }}                   # Operating system
+{{ context.environment }}                 # "staging" or "production"
 ```
 
-### Events
+#### Flash Messages
 
 ```liquid
-{% comment %} Publish an event {% endcomment %}
-{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %}
-
-{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %}
-{% graphql _ = 'emails/send_confirmation', email: event.object.email %}
+{{ context.flash }}                       # Flash messages hash
+{{ context.flash.notice }}                # Success message
+{{ context.flash.alert }}                 # Error message
 ```
 
-All inputs MUST be validated in commands before persisting.
+**Available Device Types:**
+- `desktop`
+- `smartphone`
+- `tablet`
+- `console`
+- `portable media player`
+- `tv`
+- `car browser`
+- `camera`
+
+**Available HTTP Headers:**
+- `SERVER_NAME`
+- `REQUEST_METHOD`
+- `PATH_INFO`
+- `REQUEST_URI`
+- `HTTP_AUTHORIZATION`
 
 ---
 
-## 7. GraphQL
+## 5. Records & Tables
 
-GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively.
+### Defining Tables
 
-### Query Wrapper Pattern
+Tables define data structure in `app/schema/` as YAML files.
 
-```liquid
-{% doc %}
-  @param id {string} - Article ID
-{% enddoc %}
+**File:** `app/schema/blog_post.yml`
+```yaml
+name: blog_post
+properties:
+  - name: title
+    type: string
+  - name: content
+    type: text
+  - name: published_at
+    type: datetime
+  - name: author_id
+    type: string
+  - name: tags
+    type: array
+  - name: metadata
+    type: jsonb
+```
+
+### Property Types Reference
+
+| Type | Description | Liquid Equivalent |
+|------|-------------|-------------------|
+| `string` | Short text (255 chars) | String |
+| `text` | Long text | String |
+| `integer` | Whole numbers | Integer |
+| `float` | Decimal numbers | Float |
+| `boolean` | true/false | Boolean |
+| `date` | Date only | Date |
+| `datetime` | Date + Time | DateTime |
+| `array` | List of values | Array |
+| `jsonb` | JSON data | Hash |
+| `geojson` | Geographic data | GeoJSON Object |
+| `upload` | File attachment | Upload Object |
+
+### Record Lifecycle
 
-{% liquid
-  graphql result = 'articles/find', id: id
-  return result.records.results | first
-%}
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
+│  Create │───▶│  Read   │───▶│ Update  │───▶│ Delete  │
+│  record │    │  record │    │ record  │    │ record  │
+└─────────┘    └─────────┘    └─────────┘    └─────────┘
+     │              │              │              │
+  GraphQL       GraphQL        GraphQL        GraphQL
+  mutation       query         mutation       mutation
 ```
 
-### Search with Pagination
+### Creating Records via GraphQL
 
+**File:** `app/graphql/records/create_blog_post.graphql`
 ```graphql
-query search($page: Int = 1, $keyword: String) {
-  records(
-    page: $page
-    per_page: 20
-    filter: {
-      table: { value: "article" }
-      properties: [{ name: "title", contains: $keyword }]
+mutation create_blog_post(
+  $title: String!
+  $content: String!
+  $author_id: String!
+) {
+  record_create(
+    record: {
+      table: "blog_post"
+      properties: [
+        { name: "title", value: $title }
+        { name: "content", value: $content }
+        { name: "author_id", value: $author_id }
+      ]
     }
-    sort: { created_at: { order: DESC } }
   ) {
-    total_pages
-    results {
-      id
-      title: property(name: "title")
-      body: property(name: "body")
-    }
+    id
+    created_at
+    properties
   }
 }
 ```
 
-All list queries MUST support `per_page` and `page` arguments for pagination.
-
-### Find by ID
+### Querying Records
 
+**File:** `app/graphql/records/get_blog_posts.graphql`
 ```graphql
-query find($id: ID!) {
+query get_blog_posts(
+  $limit: Int = 10
+  $published: Boolean = true
+) {
   records(
-    per_page: 1
+    per_page: $limit
     filter: {
-      id: { value: $id }
-      table: { value: "article" }
+      table: { value: "blog_post" }
+      properties: [
+        { name: "published", value_boolean: $published }
+      ]
     }
+    sort: [{ created_at: { order: DESC } }]
   ) {
     results {
       id
-      title: property(name: "title")
+      created_at
+      properties
     }
+    total_entries
+    total_pages
   }
 }
 ```
 
-### Related Records (Avoids N+1)
+### CRUD Operations Summary
 
-```graphql
-results {
-  id
-  # belongs-to (single)
-  author: related_record(table: "user", join_on_property: "user_id") {
-    email
-  }
-  # has-many
-  comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") {
-    body: property(name: "body")
-  }
-}
-```
+| Operation | GraphQL | Example |
+|-----------|---------|---------|
+| Create | `record_create` | Create new record |
+| Read | `records`, `record` | Query records |
+| Update | `record_update` | Modify existing |
+| Delete | `record_delete` | Soft/hard delete |
 
-### Upload Property
+---
 
-```graphql
-image: property_upload(name: "image") { url }
+## 6. Properties
+
+### Property Configuration
+
+Properties are defined in Table YAML files:
+
+```yaml
+properties:
+  - name: status
+    type: string
+    default: draft
+  
+  - name: view_count
+    type: integer
+    default: 0
+  
+  - name: settings
+    type: jsonb
+  
+  - name: tags
+    type: array
 ```
 
-### Mutations
+### Array Properties
+
+Arrays can store multiple values of any type:
+
+```yaml
+properties:
+  - name: tags
+    type: array
+```
 
-All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`:
+**GraphQL mutation:**
+```graphql
+mutation {
+  record_create(
+    record: {
+      table: "blog_post"
+      properties: [
+        { name: "tags", value_array: ["tech", "news", "featured"] }
+      ]
+    }
+  ) {
+    id
+  }
+}
+```
 
-- `record: record_create(record: { table: "...", properties: [...] }) { id }`
-- `record: record_update(id: $id, record: { properties: [...] }) { id }`
-- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table"
+### JSONB Properties
 
-### Pagination Component
+Store complex nested data:
 
-```liquid
-{% graphql result = 'products/search', page: context.params.page %}
-{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %}
+```yaml
+properties:
+  - name: metadata
+    type: jsonb
 ```
 
----
+**GraphQL mutation:**
+```graphql
+mutation {
+  record_create(
+    record: {
+      table: "blog_post"
+      properties: [
+        { 
+          name: "metadata", 
+          value_json: "{\"seo_title\": \"My Post\", \"keywords\": [\"a\", \"b\"]}"
+        }
+      ]
+    }
+  ) {
+    id
+  }
+}
+```
 
-## 8. Schema
+### Upload Properties
 
-Schema files define database tables in YAML at `app/schema/`.
+Handle file uploads:
 
 ```yaml
-# app/schema/article.yml
-name: article
 properties:
-  - name: title
-    type: string
-  - name: body
-    type: text
-  - name: published_at
-    type: datetime
-  - name: image
+  - name: avatar
     type: upload
-    options:
-      acl: public
 ```
 
-### Property Types
-
-`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload`
+**In forms:**
+```liquid
+{% form %}
+  
+  
+{% endform %}
+```
 
 ---
 
-## 9. Liquid Reference
+## 7. Forms
+
+### Form Structure
 
-### Tags
+Forms have two sections: YAML configuration + Liquid implementation.
 
+**File:** `app/forms/contact_form.liquid`
 ```liquid
-{% graphql result = 'query_name', arg: value %}
-{% function result = 'path/to/partial', arg: value %}
-{% render 'partial', var: value %}
-{% doc %} @param name {Type} - description {% enddoc %}
-{% return result %}
-{% export my_var, namespace: 'my_ns' %}
-{% parse_json data %}{"key": "value"}{% endparse_json %}
-{% redirect_to '/path', status: 302 %}
-{% session key = value %}
-{% log variable, type: 'debug' %}
-{% cache 'key', expire: 3600 %}...{% endcache %}
-{% background source_name: 'job_name', priority: 'low' %}...{% endbackground %}
-{% content_for_layout %}
-{% theme_render_rc 'modules/common-styling/toasts' %}
-```
+---
+name: contact_form
+resource: contact_message
+resource_owner: anyone
+redirect_to: /contact/thank-you
+flash_notice: Message sent successfully!
+fields:
+  properties:
+    name:
+      validation:
+        presence: true
+    email:
+      validation:
+        presence: true
+        email: true
+    message:
+      validation:
+        presence: true
+        length:
+          minimum: 10
+email_notifications:
+  - contact_notification
+authorization_policies:
+  - not_spam_policy
+---
 
-**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is).
+{% form %}
+  
      
+    
+    
+    {% if form.fields.properties.name.errors %}
+      {{ form.fields.properties.name.errors }}
+    {% endif %}
+  
      
+  
+  
      
+    
+    
+  
      
+  
+  
      
+    
+    
+  
      
+  
+  
+{% endform %}
+```
 
-### Output
+### Form Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `name` | Unique form identifier |
+| `resource` | Associated table name |
+| `resource_owner` | `anyone`, `self`, `anyone_with_token` |
+| `redirect_to` | URL after successful submission |
+| `flash_notice` | Success message |
+| `flash_alert` | Error message |
+| `fields` | Field definitions and validation |
+| `email_notifications` | Emails to send |
+| `api_call_notifications` | API calls to make |
+| `callback_actions` | Synchronous Liquid code |
+| `async_callback_actions` | Background job code |
+| `authorization_policies` | Access control |
+| `default_payload` | JSON payload to merge |
+
+### Validation Options
 
-```liquid
-{{ variable }}              
-{{ variable | html_safe }}  
-{% print variable %}        
+```yaml
+fields:
+  properties:
+    email:
+      validation:
+        presence:
+          message: Email is required
+        email: true
+        uniqueness:
+          message: Email already exists
+    password:
+      validation:
+        length:
+          minimum: 8
+          message: Password too short
+        confirmation: true  # Requires password_confirmation field
+    age:
+      validation:
+        numericality:
+          greater_than: 0
+          less_than: 150
+    website:
+      validation:
+        url: true
 ```
 
-### Common Filters
+### Rendering Forms in Pages
 
-- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by`
-- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys`
-- **Dates:** `add_to_time`, `localize`, `is_date_in_past`
-- **Validation:** `is_email_valid`, `is_json_valid`
-- **Encoding:** `json`, `base64_encode`, `url_encode`
+```liquid
+---
+slug: contact
+---
 
-### Coding Standards
+
      Contact Us
      
 
-You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line.
+{% render_form 'contact_form' %}
 
-**Correct:**
-```liquid
-{% liquid
-  assign filtered = products | where: 'available', true | map: 'title' | first
-  assign price = product | where: 'id', pid | map: 'price' | first
-%}
+
+
      
+  {% render_form 'contact_form', class: 'contact-form' %}
+
      
 ```
 
-**WRONG (causes syntax errors):**
+### Form Object Structure
+
 ```liquid
-{% liquid
-  assign filtered = products
-    | where: 'available', true
-    | map: 'title'
-    | first
-%}
+{{ form.fields.properties.FIELD_NAME.name }}      # Input name attribute
+{{ form.fields.properties.FIELD_NAME.value }}     # Current value
+{{ form.fields.properties.FIELD_NAME.errors }}    # Validation errors
+{{ form.errors }}                                  # All form errors
+{{ form.valid? }}                                  # Boolean validation state
 ```
 
 ---
 
-## 10. Global Context
+## 8. Liquid Templating
 
-**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results.
+### platformOS Liquid Tags
 
-| Property | Description |
-|----------|-------------|
-| `context.params` | HTTP parameters (query string + body) |
-| `context.session` | Server-side session storage |
-| `context.location` | URL info (`pathname`, `search`, `host`) |
-| `context.environment` | `staging` or `production` |
-| `context.is_xhr` | `true` for AJAX requests |
-| `context.authenticity_token` | CSRF token |
-| `context.constants` | Environment constants (hidden from `{{ context }}` for security) |
-| `context.page.metadata` | Page metadata from front matter |
+#### Query Tag (GraphQL Execution)
 
-You MUST NOT use `context.current_user` directly — always use `modules/user/queries/user/current`.
+```liquid
+{% graphql my_query = 'get_blog_posts', limit: 10 %}
 
----
+{% for post in my_query.records.results %}
+  
      {{ post.properties.title }}
      
+{% endfor %}
+```
 
-## 11. User Module (Authentication & Authorization)
+#### Background Tag (Async Jobs)
 
-You MUST use the User Module for all authentication and authorization. You MUST NOT use `authorization_policies/` directly. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested.
+```liquid
+{% background job_id = 'send_email', delay: 0.5, priority: 'high', max_attempts: 3 %}
+  {% graphql result = 'send_notification', user_id: user_id %}
+  {% log result %}
+{% endbackground %}
+```
 
-### Built-in Roles
+**Background Options:**
+- `delay`: Minutes to delay (default: 0)
+- `priority`: `low`, `default`, `high`
+- `max_attempts`: 1-5 retries (default: 1)
+- `source_name`: Job identifier label
 
-- **Anonymous** — unauthenticated users
-- **Authenticated** — any logged-in user
-- **Superadmin** — bypasses ALL permission checks
+**CRITICAL:** Variables must be explicitly passed to background:
+```liquid
+{% background data: my_data, user_id: user.id %}
+  {{ data }}  {# Available #}
+  {{ my_data }}  {# NOT available - wasn't passed #}
+{% endbackground %}
+```
 
-### Authorization Helpers
+#### Include/Render Tags
 
 ```liquid
-{% function profile = 'modules/user/queries/user/current' %}
+{# Include with local variables #}
+{% include 'header', title: 'My Page', show_nav: true %}
 
-{% comment %} Check permission (returns true/false) {% endcomment %}
-{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %}
+{# Render (preferred - isolated scope) #}
+{% render 'product_card', product: product %}
 
-{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %}
-{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %}
-
-{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %}
-{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %}
+{# Render with collection #}
+{% render 'product_card' for products as product %}
 ```
 
-> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`.
-
-### Custom Permissions
+#### Function Tag
 
-Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`:
+```liquid
+{% function my_result = 'helpers/calculate_total', items: cart_items %}
 
-```bash
-mkdir -p app/modules/user/public/lib/queries/role_permissions
-cp modules/user/public/lib/queries/role_permissions/permissions.liquid \
-   app/modules/user/public/lib/queries/role_permissions/permissions.liquid
+{# In app/views/partials/helpers/calculate_total.liquid #}
+{% return items | sum: 'price' %}
 ```
 
-Define roles:
+#### Parse JSON Tag
+
 ```liquid
-{% parse_json data %}
-{
-  "admin": ["admin.view", "users.manage"],
-  "editor": ["article.create", "article.update"],
-  "superadmin": []
-}
+{% parse_json my_data %}
+  {
+    "name": "John",
+    "items": [1, 2, 3]
+  }
 {% endparse_json %}
-{% return data %}
+
+{{ my_data.name }}  {# John #}
 ```
 
----
+#### Cache Tag
 
-## 12. Core Module
+Cache expensive operations to improve performance:
 
-You MUST use pos-module-core for commands, events, and validators.
+```liquid
+{% cache key: 'sidebar_categories', expire: 3600 %}
+  {% graphql categories = 'get_categories' %}
+  {% for category in categories.records.results %}
+    {{ category.properties.name }}
+  {% endfor %}
+{% endcache %}
+```
 
----
+**Cache Options:**
+- `key` - Unique cache identifier
+- `expire` - Cache lifetime in seconds
+- `if` - Conditional caching
 
-## 13. Common Styling
+```liquid
+{% cache key: 'user_stats', expire: 300, if: context.current_user %}
+  {# Only cache for logged-in users #}
+{% endcache %}
+```
 
-You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components.
+#### Log Tag
 
-### Setup
+Debug by logging to instance logs:
 
 ```liquid
-{% comment %} In  {% endcomment %}
-{% render 'modules/common-styling/init' %}
-```
-```html
-
+{% log 'Debug message' %}
+{% log user_id: user.id, action: 'purchase' %}
+{% log my_variable %}
 ```
 
-### File Upload Component
+View logs with: `pos-cli logs staging`
+
+#### Content For Tag
+
+Inject content into layouts:
 
 ```liquid
-{% render 'modules/common-styling/forms/upload',
-  id: 'image', presigned_upload: presigned, name: 'image',
-  allowed_file_types: ['image/*'], max_number_of_files: 5
-%}
+{# In page #}
+{% content_for 'head' %}
+  
+  
+{% endcontent_for %}
+
+{# In layout #}
+
+  {{ content_for_head }}
+
 ```
 
----
+#### Yield Tag
 
-## 14. Translations (i18n)
+Define content blocks in layouts:
 
-You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`.
+```liquid
+{# In layout #}
+
+
+{# In page #}
+{% content_for 'sidebar' %}
+  
      
+    
      Related Links
      
+  
      
+{% endcontent_for %}
+```
 
----
+#### Return Tag
 
-## 15. Forms
+Return values from function partials:
 
-You MUST use HTML `` tags. You MUST NOT use `{% form %}`.
+```liquid
+{# app/views/partials/calculate_tax.liquid #}
+{% assign tax = amount | times: 0.2 %}
+{% return tax %}
 
-Forms MUST include the CSRF token:
-```html
-
+{# Usage #}
+{% function tax_amount = 'calculate_tax', amount: 100 %}
+Tax: {{ tax_amount }}
 ```
 
-For PUT/DELETE, forms MUST use POST with a `_method` hidden field:
-```html
-
-  
-  
-  
-
+#### Raw Tag
+
+Prevent Liquid from processing content:
+
+```liquid
+{% raw %}
+  {{ this will not be processed }}
+  {% if true %}neither will this{% endif %}
+{% endraw %}
 ```
 
-Form fields MUST use bracket notation for resource binding:
-```html
-
+#### Liquid Tag (New Syntax)
+
+Use the new Liquid tag syntax for cleaner code:
+
+```liquid
+{% liquid
+  assign user = context.current_user
+  if user
+    echo 'Hello, ' | append: user.first_name
+  else
+    echo 'Hello, Guest'
+  endif
+%}
 ```
 
-Access in page: `context.params.resource`
+### Complete platformOS Tag Reference
+
+| Tag | Purpose |
+|-----|---------|
+| `{% graphql %}` | Execute GraphQL queries |
+| `{% background %}` | Run async background jobs |
+| `{% form %}` | Render form with CSRF protection |
+| `{% render_form %}` | Include a form by name |
+| `{% include %}` | Include partial (deprecated, use render) |
+| `{% render %}` | Render partial with isolated scope |
+| `{% function %}` | Call function partial with return value |
+| `{% parse_json %}` | Parse JSON string to object |
+| `{% cache %}` | Cache content fragment |
+| `{% log %}` | Log to instance logs |
+| `{% content_for %}` | Define content for layout blocks |
+| `{% yield %}` | Insert content block in layout |
+| `{% return %}` | Return value from function |
+| `{% raw %}` | Disable Liquid processing |
+| `{% liquid %}` | New multi-line Liquid syntax |
+
+### platformOS Liquid Filters
+
+#### Array Filters
 
-HTML forms submit checkbox values as \"on\" (string), but GraphQL expects boolean field to be Boolean type, not string.
+```liquid
+{# Add to array #}
+{% assign new_array = old_array | add_to_array: 'new_item' %}
 
----
+{# Compact - remove nil values #}
+{% assign clean = array | compact %}
 
-## 16. Constants & Credentials
+{# Group by property #}
+{% assign grouped = products | group_by: 'category' %}
 
-You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`.
+{# Map/extract property #}
+{% assign names = users | map: 'name' %}
 
-### Setting Constants
+{# Sort by property #}
+{% assign sorted = products | sort_by: 'price' %}
 
-**Via CLI:**
-```bash
-pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev
-pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev
-pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev
-```
+{# Sum array values #}
+{{ order_items | sum: 'total' }}
 
-**Via GraphQL:**
-```graphql
-mutation {
-  constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") {
-    name
-  }
-}
+{# Find unique values #}
+{% assign unique_tags = all_tags | uniq %}
 ```
 
-### Accessing Constants in Liquid
+#### Date/Time Filters
 
-Constants are hidden from `{{ context }}` for security. You MUST access them explicitly:
 ```liquid
-{{ context.constants.STRIPE_SK_KEY }}
-{{ context.constants.API_BASE_URL }}
+{{ 'now' | to_time }}
+{{ '2024-01-15' | to_time | add_to_time: 1, 'week' }}
+{{ 'now' | strftime: '%Y-%m-%d %H:%M' }}
+{{ post.created_at | time_ago_in_words }}
 ```
 
-### Naming Conventions
+#### Hash/Object Filters
 
-| Use Case | Example |
-|----------|---------|
-| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` |
-| API URLs | `API_BASE_URL` |
-| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` |
+```liquid
+{# Merge hashes #}
+{% assign combined = defaults | hash_merge: overrides %}
 
-Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically.
+{# Get keys #}
+{% assign keys = config | hash_keys %}
 
----
+{# Get values #}
+{% assign values = config | hash_values %}
 
-## 17. Flash Messages & Toasts
+{# Deep clone #}
+{% assign copy = original | deep_clone %}
+```
 
-### Layout Setup (before ``)
+#### URL Filters
 
 ```liquid
-{% liquid
-  function flash = 'modules/core/commands/session/get', key: 'sflash'
-  if context.location.pathname != flash.from or flash.force_clear
-    function _ = 'modules/core/commands/session/clear', key: 'sflash'
-  endif
-  render 'modules/common-styling/toasts', params: flash
-%}
+{{ 'style.css' | asset_url }}
+{{ 'photo.jpg' | asset_url | img_tag: 'Photo' }}
+{{ user.avatar | default: 'default.png' | asset_url }}
 ```
 
-### Liquid Usage
+#### String Filters
 
 ```liquid
-{% liquid
-  function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname
-  redirect_to '/orders'
-%}
+{{ text | strip_html }}
+{{ text | truncate: 100 }}
+{{ text | truncatewords: 20 }}
+{{ text | url_encode }}
+{{ text | url_decode }}
+{{ text | md5 }}
+{{ text | sha1 }}
+{{ text | hmac_sha256: secret_key }}
+{{ text | base64_encode }}
+{{ text | base64_decode }}
+{{ text | html_safe }}           {# Mark as safe HTML #}
+{{ text | sanitize }}            {# Sanitize HTML input #}
+{{ text | escape_javascript }}   {# Escape for JS #}
+{{ text | json }}                {# Convert to JSON #}
 ```
 
-### JavaScript Usage
+#### Number/Currency Filters
 
-```javascript
-new pos.modules.toast('success', 'Saved!');
-new pos.modules.toast('error', 'Failed');
+```liquid
+{{ 1234.5 | round }}             {# 1235 #}
+{{ 1234.5 | round: 1 }}          {# 1234.5 #}
+{{ 1234.5 | ceil }}              {# 1235 #}
+{{ 1234.5 | floor }}             {# 1234 #}
+{{ 19.99 | amount_to_fractional: 'USD' }}  {# 1999 (cents) #}
+{{ 1999 | fractional_to_amount: 'USD' }}   {# 19.99 #}
+{{ 1234567 | format_number: 'en' }}        {# 1,234,567 #}
 ```
 
----
-
-## 18. Notifications (Email/SMS)
+#### Encoding/Encryption Filters
 
 ```liquid
-{% comment %} app/emails/order_confirmation.liquid {% endcomment %}
+{{ 'text' | base64_encode }}
+{{ 'ZW5jb2RlZA==' | base64_decode }}
+{{ 'text' | md5 }}
+{{ 'text' | sha1 }}
+{{ 'text' | hmac_sha256: secret_key }}
+{{ 'text' | encrypt: key, algorithm: 'aes-256-gcm' }}
+{{ 'encrypted' | decrypt: key, algorithm: 'aes-256-gcm' }}
+```
+
+**Supported Encryption Algorithms:**
+- `aes-128-cbc`, `aes-192-cbc`, `aes-256-cbc`
+- `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`
+- `aes-128-ctr`, `aes-192-ctr`, `aes-256-ctr`
+- And many more...
+
+#### URL/Link Filters
+
+```liquid
+{{ 'style.css' | asset_url }}
+{{ 'photo.jpg' | asset_url | img_tag: 'Alt text' }}
+{{ 'photo.jpg' | asset_url | img_tag: 'Alt', 'class-name' }}
+{{ '/path' | link_to: 'Click here' }}
+{{ 'page' | app_url }}           {# Generate app URL #}
+```
+
+#### Debug/Development Filters
+
+```liquid
+{{ variable | debug }}           {# Debug output #}
+{{ variable | inspect }}         {# Ruby-style inspect #}
+{{ 'code' | time_diff }}         {# Measure execution time #}
+```
+
+### Complete platformOS Filter Reference
+
+| Category | Filters |
+|----------|---------|
+| **Array** | `add_to_array`, `compact`, `group_by`, `map`, `sort_by`, `sum`, `uniq`, `flatten`, `shuffle`, `rotate`, `in_groups_of` |
+| **Date** | `to_time`, `add_to_time`, `strftime`, `time_ago_in_words`, `date_add` |
+| **Hash** | `hash_merge`, `hash_keys`, `hash_values`, `deep_clone` |
+| **String** | `strip_html`, `truncate`, `truncatewords`, `url_encode`, `md5`, `sha1`, `hmac_sha256`, `base64_encode`, `sanitize`, `html_safe` |
+| **Number** | `round`, `ceil`, `floor`, `format_number`, `amount_to_fractional`, `fractional_to_amount` |
+| **URL** | `asset_url`, `img_tag`, `link_to`, `app_url` |
+| **JSON** | `json`, `parse_json` |
+| **Debug** | `debug`, `inspect`, `time_diff` |
+
+### Whitespace Control
+
+```liquid
+{# Use hyphens to control whitespace #}
+{%- if condition -%}
+  No extra whitespace
+{%- endif -%}
+
+{# Output whitespace control #}
+{{- variable -}}
+```
+
+---
+
+## 9. GraphQL API
+
+### Query Structure
+
+All GraphQL queries are stored in `app/graphql/` with `.graphql` extension.
+
+### Record Queries
+
+**List Records:**
+```graphql
+query list_products(
+  $page: Int = 1
+  $per_page: Int = 20
+  $category: String
+) {
+  records(
+    per_page: $per_page
+    page: $page
+    filter: {
+      table: { value: "product" }
+      properties: [
+        { name: "category", value: $category }
+      ]
+    }
+    sort: [{ price: { order: ASC } }]
+  ) {
+    total_entries
+    total_pages
+    has_next_page
+    has_previous_page
+    results {
+      id
+      created_at
+      updated_at
+      deleted_at
+      type_name
+      properties
+    }
+  }
+}
+```
+
+**Single Record:**
+```graphql
+query get_product($id: ID!) {
+  record(id: $id) {
+    id
+    properties
+  }
+}
+```
+
+### Record Mutations
+
+**Create:**
+```graphql
+mutation create_product(
+  $name: String!
+  $price: Float!
+) {
+  record_create(
+    record: {
+      table: "product"
+      properties: [
+        { name: "name", value: $name }
+        { name: "price", value_float: $price }
+      ]
+    }
+  ) {
+    id
+    properties
+    errors {
+      message
+    }
+  }
+}
+```
+
+**Update:**
+```graphql
+mutation update_product(
+  $id: ID!
+  $name: String
+) {
+  record_update(
+    id: $id
+    record: {
+      properties: [
+        { name: "name", value: $name }
+      ]
+    }
+  ) {
+    id
+    properties
+  }
+}
+```
+
+**Delete:**
+```graphql
+mutation delete_product($id: ID!) {
+  record_delete(id: $id) {
+    id
+    deleted_at
+  }
+}
+```
+
+### User Queries
+
+```graphql
+# Get current user
+query current_user {
+  current_user {
+    id
+    email
+    created_at
+    properties
+  }
+}
+
+# List users
+query list_users {
+  users {
+    results {
+      id
+      email
+      properties
+    }
+  }
+}
+
+# Create user
+mutation create_user(
+  $email: String!
+  $password: String!
+) {
+  user_create(
+    user: {
+      email: $email
+      password: $password
+    }
+  ) {
+    id
+    email
+  }
+}
+```
+
+### Pagination
+
+```graphql
+query paginated_records(
+  $page: Int = 1
+  $per_page: Int = 20
+) {
+  records(
+    page: $page
+    per_page: $per_page
+    filter: { table: { value: "post" } }
+  ) {
+    total_entries
+    total_pages
+    has_next_page
+    has_previous_page
+    results { id }
+  }
+}
+```
+
+### Filtering
+
+```graphql
+query filtered_records {
+  records(
+    filter: {
+      table: { value: "product" }
+      properties: [
+        { name: "status", value: "active" }
+        { name: "price", range: { gte: 10, lte: 100 } }
+      ]
+      created_at: { gte: "2024-01-01" }
+    }
+  ) {
+    results { id }
+  }
+}
+```
+
+---
+
+## 10. Users & Authentication
+
+### User Properties
+
+Define custom user properties in `app/user.yml`:
+
+```yaml
+properties:
+  - name: role
+    type: string
+    default: customer
+  - name: first_name
+    type: string
+  - name: last_name
+    type: string
+  - name: last_sign_in_at
+    type: datetime
+```
+
+### Built-in User Fields
+
+| Field | Description |
+|-------|-------------|
+| `email` | Unique identifier (case-insensitive) |
+| `password` | Virtual field (bcrypt2 hashed) |
+| `encrypted_password` | Stored hash |
+| `created_at` | Registration timestamp |
+| `updated_at` | Last update timestamp |
+
+### Authentication Flow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Sign Up   │────▶│   Sign In   │────▶│   Session   │
+│   (Form)    │     │   (Form)    │     │  (Cookie)   │
+└─────────────┘     └─────────────┘     └─────────────┘
+                                              │
+                                       ┌──────┴──────┐
+                                       ▼             ▼
+                                ┌──────────┐  ┌──────────┐
+                                │  Logout  │  │  Access  │
+                                │  (Form)  │  │  Pages   │
+                                └──────────┘  └──────────┘
+```
+
+### Session Management
+
+```liquid
+{# Check if user is logged in #}
+{% if context.current_user %}
+  
      Welcome, {{ context.current_user.email }}
      
+{% else %}
+  Sign In
+{% endif %}
+
+{# Access user properties #}
+{{ context.current_user.properties.role }}
+{{ context.current_user.properties.first_name }}
+```
+
+### Sign In Form
+
+**File:** `app/forms/sign_in_form.liquid`
+```liquid
+---
+name: sign_in_form
+resource: session
+resource_owner: anyone
+redirect_to: /
+flash_alert: Invalid email or password
+---
+
+{% form %}
+  
+  
+  
+{% endform %}
+```
+
+### Sign Up Form
+
+**File:** `app/forms/sign_up_form.liquid`
+```liquid
+---
+name: sign_up_form
+resource: user
+resource_owner: anyone
+redirect_to: /welcome
+flash_notice: Account created!
+fields:
+  email:
+    validation:
+      presence: true
+      email: true
+      uniqueness: true
+  password:
+    validation:
+      presence: true
+      length:
+        minimum: 8
+---
+
+{% form %}
+  
+  
+  
+{% endform %}
+```
+
+---
+
+## 11. Authorization Policies
+
+### Creating Policies
+
+**File:** `app/authorization_policies/valid_user.liquid`
+```liquid
+---
+name: valid_user_policy
+redirect_to: /sign-in
+flash_alert: Please sign in to access this page
+---
+
+{% if context.current_user %}
+  true
+{% else %}
+  false
+{% endif %}
+```
+
+### Policy Configuration
+
+| Option | Description |
+|--------|-------------|
+| `name` | Policy identifier |
+| `redirect_to` | Where to redirect if policy fails |
+| `flash_alert` | Error message on failure |
+
+### Associating with Pages
+
+```liquid
+---
+slug: admin/dashboard
+authorization_policies:
+  - valid_user_policy
+  - admin_only_policy
+---
+```
+
+### Associating with Forms
+
+```liquid
+---
+name: delete_product_form
+resource: product
+authorization_policies:
+  - valid_user_policy
+  - product_owner_policy
+---
+```
+
+### Common Policy Patterns
+
+**Admin Only:**
+```liquid
+{% if context.current_user.properties.role == 'admin' %}
+  true
+{% else %}
+  false
+{% endif %}
+```
+
+**Resource Owner:**
+```liquid
+{% graphql product = 'get_product', id: context.params.id %}
+{% if product.record.properties.owner_id == context.current_user.id %}
+  true
+{% else %}
+  false
+{% endif %}
+```
+
+---
+
+## 12. Modules
+
+### Module Structure
+
+```
+modules/
+└── my_module/
+    ├── public/
+    │   ├── views/
+    │   ├── forms/
+    │   ├── graphql/
+    │   └── assets/
+    └── private/
+        ├── views/
+        └── forms/
+```
+
+### Module Namespacing
+
+All module files are prefixed with `modules/MODULE_NAME/`:
+
+```liquid
+{# Reference module partial #}
+{% render 'modules/my_module/header' %}
+
+{# Reference module GraphQL #}
+{% graphql result = 'modules/my_module/get_data' %}
+
+{# Reference module form #}
+{% render_form 'modules/my_module/contact_form' %}
+
+{# Reference module asset #}
+{{ 'modules/my_module/style.css' | asset_url }}
+```
+
+### Installing Modules
+
+```bash
+# Install from Partner Portal
+pos-cli modules install module_name
+
+# Install specific version
+pos-cli modules install module_name@1.2.3
+```
+
+### Overwriting Module Files
+
+Create a file with the same path in your `app` directory:
+
+```
+app/
+└── views/
+    └── partials/
+        └── modules/
+            └── my_module/
+                └── header.liquid  # Overrides module version
+```
+
+### Creating Modules
+
+1. Create directory: `modules/MODULE_NAME/`
+2. Add `public/` and/or `private/` subdirectories
+3. Structure mirrors `app/` directory
+4. Deploy with `pos-cli deploy`
+
+---
+
+## 13. Background Jobs
+
+### When to Use Background Jobs
+
+| Use Case | Example |
+|----------|---------|
+| Email sending | Welcome emails, notifications |
+| API calls | Webhooks, external integrations |
+| Data processing | Imports, exports, reports |
+| Scheduled tasks | Daily cleanup, reminders |
+| Long operations | Image processing, batch updates |
+
+### Background Tag Syntax
+
+```liquid
+{% background 
+  job_id = 'unique_job_id',
+  delay: 5.0,           # Delay in minutes
+  priority: 'high',      # low, default, high
+  max_attempts: 3,       # 1-5 retries
+  source_name: 'my_job'  # Human-readable label
+%}
+  {# Your async code here #}
+  {% graphql result = 'send_email', to: email %}
+  {% log result %}
+{% endbackground %}
+```
+
+### Priority Levels
+
+| Priority | Max Execution | Use Case |
+|----------|---------------|----------|
+| `high` | 1 minute | Critical, time-sensitive |
+| `default` | 5 minutes | Standard operations |
+| `low` | 60 minutes | Background processing |
+
+### Variable Passing
+
+```liquid
+{% assign user_id = context.current_user.id %}
+{% assign data = '{"key": "value"}' | parse_json %}
+
+{% background user_id: user_id, data: data %}
+  {# Variables available: user_id, data, context #}
+  {% graphql user = 'get_user', id: user_id %}
+  {% log user %}
+{% endbackground %}
+```
+
+**IMPORTANT:** Only explicitly passed variables are available inside background blocks.
+
+### Monitoring Jobs
+
+```graphql
+query list_background_jobs {
+  background_jobs(
+    per_page: 10
+    sort: [{ created_at: { order: DESC } }]
+  ) {
+    results {
+      id
+      source_name
+      priority
+      attempts
+      max_attempts
+      created_at
+      started_at
+      completed_at
+      failed_at
+      error_message
+    }
+  }
+}
+```
+
+---
+
+## 14. Notifications
+
+### Email Notifications
+
+**File:** `app/emails/welcome_user.liquid`
+```liquid
+---
+name: welcome_user
+to: '{{ form.email }}'
+from: 'noreply@example.com'
+subject: 'Welcome to Our Platform!'
+layout: mailer
+---
+
+
      Welcome, {{ form.name }}!
      
+
      Thank you for joining us.
      
+
+
      Get Started
      
+```
+
+**Email Configuration Options:**
+
+| Option | Description |
+|--------|-------------|
+| `name` | Notification identifier |
+| `to` | Recipient email (Liquid) |
+| `from` | Sender email |
+| `subject` | Email subject (Liquid) |
+| `layout` | Email layout template |
+| `bcc` | BCC recipients |
+| `cc` | CC recipients |
+
+### SMS Notifications
+
+**File:** `app/smses/verification_code.liquid`
+```liquid
+---
+name: verification_code
+to: '{{ form.phone_number }}'
+---
+
+Your verification code is: {{ form.verification_code }}
+```
+
+### API Call Notifications
+
+**File:** `app/api_calls/webhook.liquid`
+```liquid
+---
+name: webhook_notification
+to: 'https://api.example.com/webhook'
+format: json
+callback: ''
+request_type: POST
+headers: >
+  {
+    "Authorization": "Bearer {{ context.constants.api_key }}",
+    "Content-Type": "application/json"
+  }
+---
+
+{
+  "event": "user_signup",
+  "user_id": "{{ form.id }}",
+  "email": "{{ form.email }}",
+  "timestamp": "{{ 'now' | to_time }}"
+}
+```
+
+### Triggering Notifications
+
+From forms:
+```yaml
+---
+name: contact_form
+email_notifications:
+  - contact_confirmation
+  - admin_notification
+api_call_notifications:
+  - crm_webhook
+sms_notifications:
+  - sms_confirmation
+---
+```
+
+---
+
+## 15. Assets & Uploads
+
+### Assets (Static Files)
+
+Assets are files in `app/assets/` that are served via CDN.
+
+**Directory Structure:**
+```
+app/assets/
+├── css/
+│   └── app.css
+├── js/
+│   └── app.js
+├── images/
+│   └── logo.png
+└── fonts/
+    └── custom.woff2
+```
+
+**Using Assets:**
+```liquid
+
+
+Logo
+```
+
+### User Uploads
+
+Uploads are dynamic files stored per-record.
+
+**Table Definition:**
+```yaml
+name: product
+properties:
+  - name: image
+    type: upload
+```
+
+**Form:**
+```liquid
+{% form %}
+  
+{% endform %}
+```
+
+**Displaying Uploads:**
+```liquid
+{% graphql product = 'get_product', id: id %}
+{{ product.record.properties.image.file_name }}
+```
+
+**Upload Properties:**
+
+| Property | Description |
+|----------|-------------|
+| `url` | Direct file URL |
+| `file_name` | Original filename |
+| `content_type` | MIME type |
+| `size` | File size in bytes |
+
+### Assets vs Uploads
+
+| Aspect | Assets | Uploads |
+|--------|--------|---------|
+| Location | `app/assets/` | Record properties |
+| Use Case | Static files (CSS, JS, logos) | Dynamic content |
+| Quantity | Thousands expected | Millions supported |
+| CDN | Yes | Yes |
+| Max Size | 2GB | 2GB |
+
+### Direct S3 Upload
+
+platformOS uses **direct S3 upload** - files go straight to AWS S3 without passing through the application server.
+
+**Advantages:**
+- **Speed** - No middleman, faster uploads
+- **Cost** - Less bandwidth and server load
+- **Security** - No file processing on app server
+- **Scalability** - Handle unlimited concurrent uploads
+- **Size** - Up to 5GB single file, 5TB multipart
+
+**Upload Flow:**
+```
+1. User selects file
+2. Browser requests signed S3 URL from platformOS
+3. Browser uploads directly to S3
+4. S3 returns success
+5. platformOS saves file reference to record
+```
+
+### Upload Configuration Options
+
+**Table Definition with Options:**
+```yaml
+name: product
+properties:
+  - name: image
+    type: upload
+    options:
+      public: true              # Public or private access
+      max_size: 5242880         # 5MB in bytes
+      versions:
+        - name: thumbnail
+          resize: '200x200>'    # Resize to fit 200x200
+        - name: medium
+          resize: '800x600>'
+      extensions:
+        - jpg
+        - png
+        - gif
+```
+
+### Upload Versions
+
+Automatically generate resized versions:
+
+```yaml
+properties:
+  - name: photo
+    type: upload
+    options:
+      versions:
+        - name: thumb
+          resize: '100x100#'    # Exact fit, may crop
+        - name: medium
+          resize: '300x300>'    # Fit within, no upscale
+        - name: large
+          resize: '800x800>'
+```
+
+**Access versions in Liquid:**
+```liquid
+{{ product.properties.photo.url }}           # Original
+{{ product.properties.photo.versions.thumb.url }}   # Thumbnail
+{{ product.properties.photo.versions.medium.url }}  # Medium
+```
+
+### Image Processing Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `resize: '100x100'` | Resize to dimensions | Fit within |
+| `resize: '100x100>'` | Resize only if larger | Downscale only |
+| `resize: '100x100<'` | Resize only if smaller | Upscale only |
+| `resize: '100x100#'` | Exact dimensions | May crop |
+| `resize: '100x100^'` | Minimum dimensions | May crop |
+
+---
+
+## 16. Best Practices
+
+### Code Organization
+
+```
+app/
+├── views/
+│   ├── pages/           # Route handlers
+│   ├── layouts/         # Page wrappers
+│   └── partials/
+│       ├── components/  # UI components
+│       ├── forms/       # Form partials
+│       └── helpers/     # Utility partials
+├── forms/               # Form configurations
+├── graphql/             # Data queries
+│   ├── records/
+│   ├── users/
+│   └── system/
+└── schema/              # Table definitions
+```
+
+### Naming Conventions
+
+| Component | Convention | Example |
+|-----------|------------|---------|
+| Tables | snake_case | `blog_post` |
+| Properties | snake_case | `published_at` |
+| Pages | snake_case | `about_us.liquid` |
+| Partials | snake_case | `header.liquid` |
+| Forms | snake_case | `contact_form.liquid` |
+| GraphQL | snake_case | `get_blog_posts.graphql` |
+
+### Security Best Practices
+
+1. **Always use authorization policies** for protected routes
+2. **Validate all inputs** using form validations
+3. **Escape output** using Liquid's auto-escaping
+4. **Use HTTPS** for all production instances
+5. **Store secrets** in Partner Portal constants, not code
+6. **Sanitize user content** before displaying
+
+### Performance Best Practices
+
+1. **Use pagination** for all list queries
+2. **Load related records** in single GraphQL query
+3. **Use background jobs** for long operations
+4. **Cache expensive queries** using static cache
+5. **Optimize images** before uploading as assets
+6. **Minimize GraphQL response size** with specific field selection
+
+### Error Handling
+
+```liquid
+{% graphql result = 'create_record', name: name %}
+
+{% if result.record_create.errors %}
+  
      
+    {% for error in result.record_create.errors %}
+      
      {{ error.message }}
      
+    {% endfor %}
+  
      
+{% else %}
+  
      Success! ID: {{ result.record_create.id }}
      
+{% endif %}
+```
+
+---
+
+## 17. Common Gotchas & Pitfalls
+
+### 1. Variable Scope in Background Jobs
+
+**WRONG:**
+```liquid
+{% assign user_id = context.current_user.id %}
+{% background %}
+  {{ user_id }}  {# nil - not passed #}
+{% endbackground %}
+```
+
+**CORRECT:**
+```liquid
+{% assign user_id = context.current_user.id %}
+{% background user_id: user_id %}
+  {{ user_id }}  {# Works! #}
+{% endbackground %}
+```
+
+### 2. N+1 Query Problem
+
+**WRONG (N+1 queries):**
+```liquid
+{% graphql companies = 'get_companies' %}
+{% for company in companies.records.results %}
+  {% graphql programmers = 'get_programmers', company_id: company.id %}
+  {# Each iteration = 1 query! #}
+{% endfor %}
+```
+
+**CORRECT (single query):**
+```graphql
+query get_companies_with_programmers {
+  records(
+    filter: { table: { value: "company" } }
+  ) {
+    results {
+      id
+      properties
+      programmers: related_records(
+        table: "programmer"
+        foreign_property: "company_id"
+      ) {
+        id
+        properties
+      }
+    }
+  }
+}
+```
+
+### 3. Form Field Name Format
+
+**WRONG:**
+```liquid
+  {# Won't bind to form #}
+```
+
+**CORRECT:**
+```liquid
+
+```
+
+### 4. Module File References
+
+**WRONG:**
+```liquid
+{% render 'modules/my_module/public/header' %}
+```
+
+**CORRECT:**
+```liquid
+{% render 'modules/my_module/header' %}
+```
+
+### 5. Date/Time Formatting
+
+**WRONG:**
+```liquid
+{{ '2024-01-01' | strftime: '%Y' }}  {# Error - not a time object #}
+```
+
+**CORRECT:**
+```liquid
+{{ '2024-01-01' | to_time | strftime: '%Y' }}
+```
+
+### 6. Array vs JSONB Confusion
+
+**Arrays** - for simple lists:
+```yaml
+type: array
+# Value: ["a", "b", "c"]
+```
+
+**JSONB** - for complex objects:
+```yaml
+type: jsonb
+# Value: {"nested": {"key": "value"}}
+```
+
+### 7. Form Resource Owner
+
+**For public forms** (contact, newsletter):
+```yaml
+resource_owner: anyone
+```
+
+**For authenticated forms** (profile edit):
+```yaml
+resource_owner: self
+```
+
+**For admin forms**:
+```yaml
+resource_owner: anyone_with_token
+authorization_policies:
+  - admin_only_policy
+```
+
+### 8. Whitespace in Liquid
+
+**Problem:** Extra whitespace in output
+```liquid
+{% if true %}
+  Content
+{% endif %}
+{# Outputs newlines around content #}
+```
+
+**Solution:** Use whitespace control
+```liquid
+{%- if true -%}
+  Content
+{%- endif -%}
+```
+
+### 9. GraphQL Variable Types
+
+**Integer vs Float:**
+```graphql
+# Integer property
+{ name: "count", value_int: 5 }
+
+# Float property  
+{ name: "price", value_float: 19.99 }
+```
+
+**Boolean:**
+```graphql
+{ name: "active", value_boolean: true }
+```
+
+### 10. Soft Delete vs Hard Delete
+
+**Soft delete** (default):
+```graphql
+mutation {
+  record_delete(id: "123") {
+    id
+    deleted_at  # Timestamp set
+  }
+}
+```
+
+**Hard delete** (permanent):
+```graphql
+mutation {
+  record_delete(id: "123", hard_delete: true) {
+    id
+  }
+}
+```
+
+### 11. Reserved Names
+
+Avoid these reserved names for custom tables and properties:
+
+**System Fields (automatically created):**
+- `id` - Record UUID
+- `created_at` - Creation timestamp
+- `updated_at` - Last update timestamp
+- `deleted_at` - Soft delete timestamp
+- `type_name` - Table name
+- `properties` - Property container
+
+**Reserved Words:**
+- `user`, `users` - Built-in User table
+- `session`, `sessions` - Session management
+- `record`, `records` - Record operations
+- `constant`, `constants` - System constants
+- `table`, `tables` - Table metadata
+
+### 12. Form Resource Owner Confusion
+
+| Value | When to Use |
+|-------|-------------|
+| `anyone` | Public forms (contact, newsletter) |
+| `self` | User editing their own data |
+| `anyone_with_token` | API endpoints with token auth |
+
+**Wrong:**
+```yaml
+resource_owner: self  # Won't work for public contact form
+```
+
+**Correct:**
+```yaml
+resource_owner: anyone  # For public forms
+```
+
+### 13. Module File Deletion Behavior
+
+By default, module files are **NOT deleted** during deploy to protect private files.
+
+To enable deletion for a module:
+```yaml
+# app/config.yml
+modules_that_allow_delete_on_deploy:
+  - my_module
+```
+
+### 14. GraphQL Query Caching
+
+GraphQL queries are cached by default. To bypass cache:
+```graphql
+query {
+  records(
+    per_page: 10
+    filter: { table: { value: "product" } }
+  ) @skip_cache {
+    results { id }
+  }
+}
+```
+
+### 15. File Upload Size Limits
+
+| Upload Type | Max Size |
+|-------------|----------|
+| Direct S3 (single part) | 5 GB |
+| Direct S3 (multipart) | 5 TB |
+| Application-processed | 2 GB |
+
+### 16. Background Job Payload Limits
+
+```liquid
+{# WRONG - payload too large #}
+{% background data: huge_array_with_thousands_of_items %}
+
+{# CORRECT - pass reference only #}
+{% background record_id: record_id %}
+  {% graphql record = 'get_record', id: record_id %}
+  {# Process data in background #}
+{% endbackground %}
+```
+
+### 17. Liquid Truthiness
+
+In Liquid, only `nil` and `false` are falsy. Empty strings and zero are truthy:
+
+```liquid
+{% if '' %}TRUE{% endif %}     {# TRUE! #}
+{% if 0 %}TRUE{% endif %}       {# TRUE! #}
+{% if empty_array %}TRUE{% endif %}  {# FALSE (nil) #}
+{% if false %}TRUE{% endif %}    {# FALSE #}
+```
+
+Use `blank` and `present` for better checks:
+```liquid
+{% if '' == blank %}EMPTY{% endif %}  {# EMPTY #}
+{% if 0 == blank %}ZERO IS BLANK{% endif %}  {# Not blank! #}
+```
+
+---
+
+## 18. Performance Optimization
+
+### Measuring Performance
+
+**time_diff filter:**
+```liquid
+{% assign start = 'now' | to_time %}
+
+{% graphql posts = 'get_posts' %}
+
+{% assign duration = start | time_diff: 'now' %}
+
      Query took: {{ duration }}ms
      
+```
+
+### Query Optimization
+
+**1. Select only needed fields:**
+```graphql
+# BAD - fetches everything
+query {
+  records { results { properties } }
+}
+
+# GOOD - specific fields
+query {
+  records { 
+    results { 
+      id
+      properties
+    } 
+  }
+}
+```
+
+**2. Use pagination:**
+```graphql
+query {
+  records(per_page: 20, page: 1) {
+    total_entries
+    results { id }
+  }
+}
+```
+
+**3. Load related records efficiently:**
+```graphql
+query {
+  records(filter: { table: { value: "order" } }) {
+    results {
+      id
+      items: related_records(table: "order_item") {
+        id
+        properties
+      }
+    }
+  }
+}
+```
+
+### Caching Strategies
+
+**Static Cache (Edge Caching):**
+```liquid
+---
+slug: public-page
+response_headers:
+  Cache-Control: public, max-age=3600
+---
+```
+
+**Fragment Caching:**
+```liquid
+{% cache key: 'sidebar', expire: 3600 %}
+  {% graphql categories = 'get_categories' %}
+  {% for category in categories.records.results %}
+    {{ category.properties.name }}
+  {% endfor %}
+{% endcache %}
+```
+
+### Background Job Optimization
+
+**Keep payloads small:**
+```liquid
+{# BAD - large payload #}
+{% background data: huge_array %}
+
+{# GOOD - pass reference #}
+{% assign job_id = 'process_' | append: record_id %}
+{% background job_id: job_id, record_id: record_id %}
+  {% graphql record = 'get_record', id: record_id %}
+  {# Process in background #}
+{% endbackground %}
+```
+
+---
+
+## 19. Testing & CI/CD
+
+### pos-cli GUI
+
+```bash
+# Start GUI for GraphQL development
+pos-cli gui serve staging
+
+# Access at http://localhost:3333
+```
+
+### platformOS Check
+
+```bash
+# Install
+npm install -g @platformos/platformos-check
+
+# Run checks
+platformos-check
+
+# Auto-fix issues
+platformos-check --auto-correct
+```
+
+### GitHub Actions CI
+
+**File:** `.github/workflows/platformos.yml`
+```yaml
+name: platformOS CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install pos-cli
+        run: npm install -g @platformos/pos-cli
+      
+      - name: Deploy to Staging
+        run: pos-cli deploy staging
+        env:
+          MPKIT_TOKEN: ${{ secrets.MPKIT_TOKEN }}
+          MPKIT_URL: ${{ secrets.STAGING_URL }}
+      
+      - name: Run Tests
+        run: npm test
+```
+
+### Release Pool Setup
+
+1. Create dedicated test instances in Partner Portal
+2. Configure GitHub secrets:
+   - `MPKIT_TOKEN`
+   - `STAGING_URL`
+   - `PRODUCTION_URL`
+
+### Testing Best Practices
+
+1. **Unit test** GraphQL queries
+2. **Integration test** form submissions
+3. **E2E test** critical user flows
+4. **Performance test** with realistic data volumes
+5. **Security test** authorization policies
+
+---
+
+## 20. System Limitations
+
+### Resource Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| File upload size | 2GB | Assets and uploads |
+| Background job payload | 100KB | Keep payloads small |
+| Background job execution | 1-60 min | Depends on priority |
+| GraphQL query complexity | Varies | Monitor performance |
+| Records per query | Unlimited | Use pagination |
+| Assets | Thousands | Use uploads for dynamic content |
+| Uploads | Millions | No practical limit |
+
+### Background Job Limits
+
+| Priority | Max Execution | Use For |
+|----------|---------------|---------|
+| `high` | 1 minute | Critical, urgent tasks |
+| `default` | 5 minutes | Standard operations |
+| `low` | 60 minutes | Heavy processing |
+
+### Rate Limiting
+
+- API calls may be rate-limited based on plan
+- Background job scheduling has queue limits
+- GraphQL queries have complexity scoring
+
+### Reserved Names
+
+Avoid these names for custom tables/properties:
+- `id`, `created_at`, `updated_at`, `deleted_at`
+- `type_name`, `properties`, `user`
+- Built-in Liquid objects and filters
+
+---
+
+## 22. Data Import/Export
+
+### Exporting Data
+
+```bash
+# Export all data from an instance
+pos-cli data export staging --path=./export.json
+
+# Export specific tables
+pos-cli data export staging --tables=products,orders --path=./products.json
+```
+
+### Importing Data
+
+```bash
+# Import data to an instance
+pos-cli data import staging ./export.json
+
+# Import with transformations
+pos-cli data import staging ./data.json --transform=./transform.js
+```
+
+### Data Export Format
+
+```json
+{
+  "users": [
+    {
+      "id": "123",
+      "email": "user@example.com",
+      "created_at": "2024-01-15T10:00:00Z",
+      "properties": {
+        "first_name": "John",
+        "last_name": "Doe"
+      }
+    }
+  ],
+  "records": {
+    "product": [
+      {
+        "id": "456",
+        "properties": {
+          "name": "Widget",
+          "price": 19.99
+        }
+      }
+    ]
+  }
+}
+```
+
+### Programmatic Import with Migrations
+
+```liquid
+{# app/migrations/20240115000000_import_products.liquid #}
+{% parse_json data %}
+  {{ 'data/products.json' | load_file }}
+{% endparse_json %}
+
+{% for product in data.products %}
+  {% graphql result = 'create_product',
+    name: product.name,
+    price: product.price,
+    sku: product.sku
+  %}
+  {% log result %}
+{% endfor %}
+```
+
+### Cleaning Instance Data
+
+```bash
+# WARNING: This deletes all data!
+pos-cli data clean staging
+
+# Clean specific tables
+pos-cli data clean staging --tables=products,orders
+```
+
 ---
-to: {{ data.email }}
-from: shop@example.com
-subject: "Order #{{ data.order_id }}"
-layout: mailer
+
+## 23. Quick Reference
+
+### File Templates
+
+**New Page:**
+```liquid
+---
+slug: my-page
+layout: application
 ---
-
      Thank you for your order!
      
+
+
      Page Title
      
 ```
 
-Emails SHOULD be sent asynchronously using events + consumers.
+**New Table:**
+```yaml
+name: my_table
+properties:
+  - name: name
+    type: string
+```
 
+**New Form:**
+```liquid
+---
+name: my_form
+resource: my_table
+resource_owner: anyone
+redirect_to: /success
+fields:
+  properties:
+    name:
+      validation:
+        presence: true
 ---
 
-## 19. Payments (Stripe)
+{% form %}
+  
+  
+{% endform %}
+```
+
+**New GraphQL Query:**
+```graphql
+query my_query($param: String) {
+  records(filter: { table: { value: "my_table" } }) {
+    results { id properties }
+  }
+}
+```
 
-### Install
+### Common Liquid Patterns
 
-```bash
-pos-cli modules install payments && pos-cli modules install payments_stripe
-pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev
+**Conditional rendering:**
+```liquid
+{% if condition %}
+  
+{% elsif other_condition %}
+  
+{% else %}
+  
+{% endif %}
 ```
 
-### Create Transaction
+**Loop with index:**
+```liquid
+{% for item in items %}
+  {{ forloop.index }}: {{ item.name }}
+{% endfor %}
+```
 
+**Pagination:**
 ```liquid
-{% function transaction = 'modules/payments/commands/transactions/create',
-  gateway: 'stripe', email: email, line_items: items,
-  success_url: '/thank-you', cancel_url: '/cart'
-%}
-{% function url = 'modules/payments/queries/pay_url', transaction: transaction %}
-{% redirect_to url, status: 303 %}
+{% if records.has_previous_page %}
+  Previous
+{% endif %}
+
+{% if records.has_next_page %}
+  Next
+{% endif %}
+```
+
+### Common GraphQL Patterns
+
+**Create with error handling:**
+```graphql
+mutation {
+  record_create(record: { table: "post", properties: [] }) {
+    id
+    errors { message }
+  }
+}
+```
+
+**Update specific fields:**
+```graphql
+mutation {
+  record_update(id: "123", record: { properties: [{ name: "status", value: "published" }] }) {
+    id
+    properties
+  }
+}
+```
+
+**Search with filters:**
+```graphql
+query {
+  records(
+    filter: {
+      table: { value: "product" }
+      properties: [{ name: "category", value: "electronics" }]
+      created_at: { gte: "2024-01-01" }
+    }
+  ) {
+    results { id }
+  }
+}
+```
+
+### pos-cli Commands
+
+```bash
+# Authentication
+pos-cli auth login                    # Login to Partner Portal
+
+# Development
+pos-cli sync staging                  # Watch and sync changes
+pos-cli deploy staging                # Deploy to instance
+pos-cli deploy staging -f             # Force deploy (delete missing files)
+
+# Data
+pos-cli data export staging           # Export instance data
+pos-cli data import staging file.json # Import data
+pos-cli migrations run staging        # Run pending migrations
+
+# Modules
+pos-cli modules install module_name   # Install module
+pos-cli modules remove module_name    # Remove module
+
+# GUI
+pos-cli gui serve staging             # Start development GUI
+
+# Logs
+pos-cli logs staging                  # Stream logs
 ```
 
-Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed`
+### Error Messages Reference
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Record not found` | Invalid ID | Check record exists |
+| `Validation failed` | Invalid data | Check form validations |
+| `Unauthorized` | Policy failed | Check authorization |
+| `Rate limited` | Too many requests | Add delays, use caching |
+| `Timeout` | Query too slow | Optimize query, add pagination |
+| `Property not found` | Wrong property name | Check table schema |
+| `Table not found` | Wrong table name | Check table definition |
+| `Form not found` | Wrong form name | Check form file exists |
+
+### GraphQL Property Type Mapping
+
+| Property Type | GraphQL Input | Example |
+|---------------|---------------|---------|
+| `string` | `value: "text"` | `{ name: "title", value: "Hello" }` |
+| `integer` | `value_int: 42` | `{ name: "count", value_int: 5 }` |
+| `float` | `value_float: 19.99` | `{ name: "price", value_float: 19.99 }` |
+| `boolean` | `value_boolean: true` | `{ name: "active", value_boolean: true }` |
+| `date` | `value: "2024-01-15"` | `{ name: "birthday", value: "2024-01-15" }` |
+| `datetime` | `value: "2024-01-15T10:00:00Z"` | ISO 8601 format |
+| `array` | `value_array: ["a", "b"]` | `{ name: "tags", value_array: ["a", "b"] }` |
+| `jsonb` | `value_json: "{}"` | JSON string |
+| `upload` | Via form only | File uploads |
+
+### Form Validation Reference
+
+| Validation | Syntax | Description |
+|------------|--------|-------------|
+| `presence` | `presence: true` | Required field |
+| `email` | `email: true` | Valid email format |
+| `uniqueness` | `uniqueness: true` | Must be unique |
+| `length` | `length: { minimum: 5, maximum: 100 }` | String length |
+| `numericality` | `numericality: { greater_than: 0 }` | Number range |
+| `confirmation` | `confirmation: true` | Must match confirmation field |
+| `url` | `url: true` | Valid URL format |
+
+### pos-cli Extended Commands
+
+```bash
+# Authentication
+pos-cli auth login                      # Login to Partner Portal
+pos-cli auth logout                     # Logout
+
+# Development
+pos-cli sync staging                    # Watch and sync changes
+pos-cli sync staging --live-reload      # With live reload
+pos-cli deploy staging                  # Deploy to instance
+pos-cli deploy staging -f               # Force deploy (delete missing files)
+pos-cli deploy staging --direct-assets  # Deploy assets directly
+
+# Data Management
+pos-cli data export staging             # Export all data
+pos-cli data export staging --tables=products,orders
+pos-cli data import staging file.json   # Import data
+pos-cli data clean staging              # Delete all data (DANGER!)
+pos-cli migrations run staging          # Run pending migrations
+pos-cli migrations status staging       # Check migration status
+
+# Modules
+pos-cli modules install module_name     # Install module
+pos-cli modules install module_name@1.2 # Specific version
+pos-cli modules remove module_name      # Remove module
+pos-cli modules list staging            # List installed modules
+
+# GUI Tools
+pos-cli gui serve staging               # Start development GUI
+pos-cli gui serve staging --port 3333   # Custom port
+
+# Logs
+pos-cli logs staging                    # Stream logs
+pos-cli logs staging --tail 100         # Last 100 lines
+pos-cli logs staging --follow           # Follow new logs
 
-**Test card:** `4242 4242 4242 4242`, any future date, any CVC.
+# Environment
+pos-cli env list                        # List environments
+pos-cli env add production              # Add environment
+pos-cli env remove staging              # Remove environment
+
+# Testing
+pos-cli test staging                    # Run tests
+
+# Debug
+pos-cli shell staging                   # Interactive shell
+```
 
 ---
 
-## 20. Migrations
+## 24. Translations
+
+### Overview
 
-Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications.
+Translations serve three main purposes:
+1. **Multi-language sites** - Static copy in multiple languages
+2. **Date formatting** - Consistent date/time display
+3. **Flash messages** - System message localization
 
-### File Structure
+### Translation Files
 
+**File:** `app/translations/en.yml`
+```yaml
+en:
+  hello: "Hello"
+  welcome: "Welcome to our site"
+  buttons:
+    submit: "Submit"
+    cancel: "Cancel"
+  errors:
+    not_found: "Page not found"
 ```
-app/migrations/
-├── 20240115120000_seed_initial_data.liquid
-├── 20240116093000_add_default_categories.liquid
-└── 20240120150000_init_staging_constants.liquid
+
+**File:** `app/translations/es.yml`
+```yaml
+es:
+  hello: "Hola"
+  welcome: "Bienvenido a nuestro sitio"
+  buttons:
+    submit: "Enviar"
+    cancel: "Cancelar"
+  errors:
+    not_found: "Página no encontrada"
 ```
 
-Files MUST be named with UTC timestamp prefix for chronological execution.
+### Using Translations in Liquid
 
-### Creating a Migration
+**Basic translation:**
+```liquid
+{{ 'hello' | t }}                    # Output: Hello (or Hola)
+```
 
-```bash
-pos-cli migrations generate dev init_staging_constants
-# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid
+**Nested keys:**
+```liquid
+{{ 'buttons.submit' | t }}           # Output: Submit
+{{ 'errors.not_found' | t }}         # Output: Page not found
 ```
 
-### Example: Initialize Staging Constants
+**With interpolation:**
+```yaml
+# en.yml
+welcome_user: "Welcome, {{ name }}!"
+```
+```liquid
+{{ 'welcome_user' | t: name: user.first_name }}
+```
 
+### Date Localization
+
+Use the `l` (localize) filter for consistent date formatting:
+
+```yaml
+# en.yml
+date:
+  formats:
+    short: "%b %d, %Y"
+    long: "%B %d, %Y %H:%M"
+```
 ```liquid
-{% liquid
-  if context.environment == 'staging'
-    graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123'
-    graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com'
-  endif
-%}
+{{ 'now' | l: 'short' }}             # Jan 15, 2024
+{{ post.published_at | l: 'long' }}  # January 15, 2024 14:30
 ```
 
-### Example: Seed Data
+### Language Detection
+
+platformOS automatically detects language from:
+1. User's `language` property (if set)
+2. Browser's Accept-Language header
+3. Default language (English)
 
+Access current language:
 ```liquid
-{% parse_json categories %}
-["Electronics", "Clothing", "Books"]
-{% endparse_json %}
+{{ context.language }}               # Current language code (e.g., "en")
+```
 
-{% for category in categories %}
-  {% graphql _ = 'categories/create', name: category %}
-{% endfor %}
+---
+
+## 25. Activity Feeds
+
+### Overview
+
+Activity Feeds implement the [W3C Activity Streams 2.0](https://www.w3.org/TR/2017/REC-activitystreams-core-20170523/) specification for tracking user activities.
+
+**Key Characteristics:**
+- Activities are **immutable** (append-only)
+- Each activity has a **unique UUID**
+- Activities can be shared between actors
+- Activities represent events that happened in the past
+
+### Activity Structure
+
+```json
+{
+  "actor": {
+    "type": "Person",
+    "id": "User.1",
+    "name": "Sally Smith"
+  },
+  "type": "Create",
+  "object": {
+    "type": "Relationship",
+    "id": "Relationship.42"
+  },
+  "target": {
+    "type": "Group",
+    "id": "Group.5"
+  }
+}
 ```
 
-### Running Migrations
+### Creating Activities
+
+**GraphQL Mutation:**
+```graphql
+mutation create_activity {
+  activity_create(
+    activity: {
+      type: "Join"
+      actor: {
+        type: "Person"
+        id: "User.123"
+        name: "John Doe"
+      }
+      object: {
+        type: "Group"
+        id: "Group.456"
+      }
+    }
+  ) {
+    id
+    uuid
+  }
+}
+```
+
+### Publishing to Feeds
 
-- **Automatic:** Pending migrations run on `pos-cli deploy`
-- **Manual:** `pos-cli migrations run TIMESTAMP dev`
+After creating an activity, publish it to feeds:
+
+```graphql
+mutation publish_to_feed {
+  feed_publish(
+    feed_id: "user_123_notifications"
+    activity_uuid: "abc-123-uuid"
+  ) {
+    id
+  }
+}
+```
 
-### Migration States
+### Querying Feeds
 
-- **pending** — not yet executed (runs on next deploy)
-- **done** — successfully completed (will not run again)
-- **error** — failed (can edit and retry)
+```graphql
+query get_user_feed {
+  feeds(
+    feed_id: "user_123_notifications"
+    per_page: 20
+  ) {
+    total_entries
+    results {
+      id
+      uuid
+      type
+      actor
+      object
+      target
+      created_at
+    }
+  }
+}
+```
 
-For large data imports, use Data Import/Export instead of migrations.
+### Common Activity Types
+
+| Type | Description |
+|------|-------------|
+| `Create` | Created something |
+| `Update` | Updated something |
+| `Delete` | Deleted something |
+| `Join` | Joined a group/event |
+| `Leave` | Left a group/event |
+| `Follow` | Started following |
+| `Like` | Liked content |
+| `Comment` | Commented on content |
+| `Share` | Shared content |
+| `Approve` | Approved a request |
 
 ---
 
-## 21. Testing
+## 26. JSON Documents
+
+### Overview
+
+JSON Documents provide a schemaless data storage option for flexible, document-based data. Unlike Records (which require a Table schema), JSON Documents can store any valid JSON structure.
+
+**Use Cases:**
+- Configuration data
+- Unstructured content
+- Temporary data storage
+- Data that doesn't fit a rigid schema
+
+### Creating JSON Documents
+
+**GraphQL Mutation:**
+```graphql
+mutation create_json_document {
+  json_document_create(
+    document: {
+      name: "site_config"
+      content: "{\"theme\": \"dark\", \"features\": [\"blog\", \"shop\"]}"
+    }
+  ) {
+    id
+    name
+    content
+    created_at
+  }
+}
+```
+
+### Querying JSON Documents
+
+```graphql
+query get_json_document {
+  json_document(name: "site_config") {
+    id
+    name
+    content
+    created_at
+    updated_at
+  }
+}
+
+query list_json_documents {
+  json_documents(
+    per_page: 10
+    sort: [{ created_at: { order: DESC } }]
+  ) {
+    results {
+      id
+      name
+      content
+    }
+  }
+}
+```
+
+### Updating JSON Documents
 
-Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development.
+```graphql
+mutation update_json_document {
+  json_document_update(
+    name: "site_config"
+    document: {
+      content: "{\"theme\": \"light\", \"features\": [\"blog\", \"shop\", \"forum\"]}"
+    }
+  ) {
+    id
+    content
+    updated_at
+  }
+}
+```
 
-Every new feature MUST have unit tests for commands.
+### Using in Liquid
 
 ```liquid
-{% function result = 'commands/products/create', title: "Test" %}
-{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %}
-{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %}
-{% return contract %}
+{% graphql config = 'get_json_document', name: 'site_config' %}
+{% assign settings = config.json_document.content | parse_json %}
+
+Theme: {{ settings.theme }}
+Features: {{ settings.features | join: ', ' }}
 ```
 
-Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI.
+### JSON Document vs Records
+
+| Feature | JSON Documents | Records |
+|---------|---------------|---------|
+| Schema | Schemaless | Defined in Table YAML |
+| Validation | None | Form validation |
+| Structure | Any JSON | Fixed properties |
+| Use Case | Config, flexible data | Structured entities |
+| GraphQL | `json_document_*` | `record_*` |
 
 ---
 
-## 22. CLI Commands
+## 27. AI Embeddings
 
-```bash
-# Deployment
-pos-cli deploy dev
+### Overview
 
-# Sync (MUST sync every file after modification)
-pos-cli sync dev
+platformOS supports AI embeddings for semantic search and similarity matching. Embeddings are vector representations of text that capture semantic meaning.
 
-# Logs
-pos-cli logs dev
+**Use Cases:**
+- Semantic search
+- Content recommendation
+- Similarity matching
+- Clustering
 
-# Linting (MUST run after EVERY file change)
-platformos-check
+### Creating Embeddings
 
-# Run Liquid inline
-pos-cli exec liquid dev ''
+**GraphQL Mutation:**
+```graphql
+mutation create_embedding {
+  embedding_create(
+    embedding: {
+      name: "product_description"
+      value: "High-quality wireless headphones with noise cancellation"
+      target_id: "product_123"
+      target_type: "Product"
+    }
+  ) {
+    id
+    vector
+  }
+}
+```
 
-# Run GraphQL inline
-pos-cli exec graphql dev ''
+### Semantic Search
 
-# Tests
-pos-cli test run staging
+```graphql
+query semantic_search {
+  embeddings_search(
+    query: "wireless audio devices"
+    limit: 10
+    threshold: 0.7
+  ) {
+    results {
+      id
+      target_id
+      target_type
+      similarity
+      value
+    }
+  }
+}
+```
 
-# Modules
-pos-cli modules install 
-pos-cli modules download 
+### Querying Embeddings
 
-# Constants
-pos-cli constants set --name KEY --value "value" dev
+```graphql
+query get_embedding {
+  embedding(
+    target_id: "product_123"
+    target_type: "Product"
+  ) {
+    id
+    name
+    value
+    vector
+    created_at
+  }
+}
+```
 
-# Generate CRUD
-pos-cli generate run modules/core/generators/crud   --include-views
+### Deleting Embeddings
 
-# Migrations
-pos-cli migrations generate dev 
-pos-cli migrations run TIMESTAMP dev
+```graphql
+mutation delete_embedding {
+  embedding_delete(
+    target_id: "product_123"
+    target_type: "Product"
+  ) {
+    id
+  }
+}
 ```
 
+### Embedding Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Identifier for the embedding type |
+| `value` | The text to embed |
+| `target_id` | ID of the associated entity |
+| `target_type` | Type of the associated entity |
+| `vector` | The computed embedding vector (read-only) |
+
 ---
 
-## 23. Modules Reference
+## 28. Migrations
 
-| Module | Install | Purpose | Required |
-|--------|---------|---------|----------|
-| `core` | Required | Commands, events, validators | YES |
-| `user` | Required | Auth, RBAC, OAuth2 | YES |
-| `common-styling` | Required | CSS, components | YES |
-| `tests` | Optional | Testing framework | YES (for testing) |
-| `payments` + `payments_stripe` | Optional | Stripe payments | No |
-| `chat` | Optional | WebSocket messaging | No |
-| `openai` | Optional | OpenAI integration | No |
+### Overview
 
----
+Migrations are Liquid scripts that run once to transform data. They are useful for:
+- Data transformations during schema changes
+- Bulk data updates
+- One-time data imports
 
-## 24. Forbidden Behaviors
-
-You MUST NOT:
-- Edit files in `./modules/` (read-only)
-- Break long lines in `{% liquid %}` blocks (causes syntax errors)
-- Invent Liquid tags, filters, or GraphQL types that do not exist
-- Use `{% form %}` tag (use HTML `
      ` only)
-- Bypass security (CSRF tokens, authorization)
-- Access databases directly outside GraphQL
-- Deploy without running `platformos-check`
-- Sync files outside `./app/`
-- Use `authorization_policies/` directly (use pos-module-user)
-- Use `context.current_user` directly (use user module queries)
-- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling)
-- Hardcode API keys, secrets, or environment-specific URLs
-- Hardcode user-facing text in partials (use translations)
-- Put HTML, JS, or CSS in page files
-- Call GraphQL from partials
-- Put raw GraphQL in pages (use `.graphql` files)
-- Create or modify application files outside the `app/` directory
-- Use more than one HTTP methods per page:
-```
-#Never try to handle POST + rendering + redirect in the same root page. Keep it clean:
-/ → GET → renders page
-/contact (or similar) → POST → processes + redirects
-```
-- Set main page methos as POST - it is not PHP!
+### Creating Migrations
 
----
+**File:** `app/migrations/20240115120000_add_status_to_products.liquid`
+```liquid
+{% graphql products = 'get_all_products' %}
+
+{% for product in products.records.results %}
+  {% graphql result = 'update_product_status', 
+    id: product.id, 
+    status: 'active' 
+  %}
+  {% log result %}
+{% endfor %}
+```
+
+### Migration File Naming
+
+Migrations are executed in alphabetical order. Use timestamps as prefixes:
+```
+app/migrations/
+├── 20240101000000_initial_setup.liquid
+├── 20240115120000_add_status.liquid
+└── 20240201000000_migrate_images.liquid
+```
+
+### Running Migrations
 
-## 25. Pre-Flight Checklist
+```bash
+# Run pending migrations
+pos-cli migrations run staging
+
+# Check migration status
+pos-cli migrations status staging
+```
 
-Before every change, verify:
+### Migration Best Practices
 
-- [ ] No underscore prefix in partial filenames
-- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid`
-- [ ] Pages have ONE HTTP method each
-- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files)
-- [ ] No HTML/JS/CSS in pages
-- [ ] No hardcoded text in partials (use translations)
-- [ ] `platformos-check` passes with 0 errors
-- [ ] Every file synced after modification
-- [ ] All list queries support pagination (`per_page`, `page`)
-- [ ] All inputs validated in commands before persisting
-- [ ] CSS/JS minified, `asset_url` used for cache busting
+1. **Make migrations idempotent** - Running twice should not cause errors:
+```liquid
+{% graphql product = 'get_product', id: product_id %}
+{% unless product.record.properties.status %}
+  {# Only update if status is not set #}
+  {% graphql result = 'update_product', id: product_id, status: 'active' %}
+{% endunless %}
+```
 
-### Asset URL Usage
+2. **Use background jobs for large migrations:**
+```liquid
+{% background source_name: 'data_migration' %}
+  {% graphql records = 'get_all_records' %}
+  {% for record in records.records.results %}
+    {# Process each record #}
+  {% endfor %}
+{% endbackground %}
+```
 
+3. **Test migrations on staging first**
+4. **Log progress for debugging:**
 ```liquid
-{{ 'images/img.png' | asset_url }}
+{% log 'Migration started' %}
+{% log 'Processed ' | append: count | append: ' records' %}
 ```
+
+### Migration Limitations
+
+- Migrations run as background jobs
+- Should complete within a few minutes
+- For long-running operations, use low-priority background jobs
+- Failed migrations can be retried
+
+---
+
+## Resources
+
+- **Documentation:** https://documentation.platformos.com/
+- **API Reference:** https://documentation.platformos.com/api-reference
+- **Examples:** https://examples.platform-os.com/
+- **GitHub:** https://github.com/Platform-OS
+- **Partner Portal:** https://partners.platformos.com/
+- **Community:** https://community.platformos.com/
+
+---
+
+*This guide is designed for LLM agents developing on platformOS. For the most up-to-date information, always refer to the official documentation.*
diff --git a/src/data/resources/short-platformos-development-guide.md b/src/data/resources/short-platformos-development-guide.md
new file mode 100644
index 0000000..21c47a3
--- /dev/null
+++ b/src/data/resources/short-platformos-development-guide.md
@@ -0,0 +1,1079 @@
+# platformOS Development Guide
+
+Every rule uses MUST/MUST NOT. No information omitted. Section 0 is the mandatory
+workflow — read it before touching any file.
+
+## 0. MANDATORY WORKFLOW — Read Before Writing Any Code
+
+**You are STRICTLY FORBIDDEN from skipping this workflow**
+
+You MUST follow this loop for every feature. Each step produces structured output
+the next step consumes — skipping any step produces invalid state that downstream
+tools will reject.
+
+1. **`project_map`** — understand what already exists. MUST be called once per session
+   before any scaffold or write.
+2. **`scaffold(type, name, properties, write: false)`** — generate the authoritative
+   file set from platformOS-native templates. MUST use scaffold whenever a file set
+   matches one of its types (crud, api, command, query, partial, page).
+3. **`domain_guide(domain)` for every domain in your plan** — BEFORE drafting files.
+   Skipping this is the #1 cause of broken platformOS code. `domain_guide` contains
+   rules that are NOT in your training data and that differ from Shopify, Rails, and
+   generic Liquid.
+4. **`validate_intent` — declare your plan before touching disk.**
+   Two modes, pick by what you're doing next:
+
+   - **Mode A — hand-drafted batch (REQUIRED before manual writes).**
+     Call `validate_intent({ intent: { goal, changes: [...] } })` where
+     `changes` is an array of `{ path, role, action, references? }` — one
+     entry per file you intend to author. The plan is the contract for the
+     rest of the session.
+   - **Mode B — scaffold review (OPTIONAL).**
+     Call `validate_intent({ scaffold_output:  })`
+     only if you want a second look at the generated set before committing.
+     The default scaffold path skips this step.
+
+   **Read the response:**
+   - `ok: false` → fix `errors[].suggestion`, re-call. MUST NOT proceed.
+   - `ok: true` + `write_directly: true` → Mode B; go straight to
+     `scaffold(..., write: true)`.
+   - `ok: true` + `write_directly: false` → Mode A; draft each file, call
+     `validate_code` on the full content, then write.
+
+   **What `pending_files` / `pending_translations` / `pending_pages` are for:**
+   you can ignore them. The supervisor stores them and uses them to suppress
+   false-positive `MissingPartial` / `TranslationKeyExists` errors in later
+   `validate_code` / `analyze_project` calls — because those files are
+   *promised* by the plan but not on disk yet. You do not pass them to any
+   subsequent tool; the server merges them automatically.
+
+   **Skipping Mode A before hand-drafted writes** is the #1 cause of phantom
+   cross-reference errors: `validate_code` will flag every partial and
+   translation key the plan hasn't written yet, and the agent chases those
+   ghosts by deleting the references the plan needs.
+
+   **Scope drift:** if you add, rename, or drop a file that isn't in the
+   current `changes` array, re-call `validate_intent` with the updated plan
+   before writing the new file.
+
+5. **`scaffold(..., write: true)`** — writes all files to disk. If you went
+   through Mode B in step 4, this runs after `write_directly: true`.
+   Otherwise this is the direct follow-up to step 2. For hand-drafted edits
+   (Mode A, or manual edits without scaffold), call `validate_code` per file
+   and only write when validation passes — never rely on scaffold to write a
+   hand-authored file.
+6. **Feedback loop.** When `validate_code` returns `status !== "ok"` or
+   `must_fix_before_write: true`, fix every error and re-validate. MUST NOT
+   write the file to disk until validation passes.
+   When debugging existing files, always read them from disk first and submit
+   their actual content to `validat_code` tool.
+7. Creation order matters: schema → graphql → partial → page.
+8. **`analyze_project` — project-wide health check.** MUST be called:
+   - **Before reporting task completion.** `validate_code` only sees one
+     file at a time; cross-file damage (broken render targets, orphaned
+     partials, dangling translations, schema drift) only surfaces from the
+     whole-project view. A task is not done until `analyze_project` returns
+     zero new errors or warnings introduced by this session.
+   - **When you feel lost.** If validate_code keeps reporting errors you
+     don't understand, if the same check keeps re-appearing after you
+     "fixed" it, if you suspect a file you edited affected callers you
+     can't see, or if `project_map` no longer matches your mental model —
+     stop editing and call `analyze_project` to re-ground. It returns
+     per-file error counts, the dependency graph, orphaned files, broken
+     references, and schema issues for every file in `app/`. That is the
+     authoritative picture of the project right now.
+
+   `analyze_project` respects `session.pending` — files declared in a
+   validated plan are not flagged as missing. You do not need to pass any
+   parameters for the standard case; omit `files` to analyze the whole
+   project.
+
+   MUST NOT: skip this step before announcing "done" just because
+   `validate_code` passed on the files you edited. Individual-file green
+   lights do not imply project integrity.
+
+
+### MUST-CALL domains (by feature type)
+
+- **Auth code** — `domain_guide(domain: "authentication")`
+- **Any form** — `domain_guide(domain: "forms")`
+- **New pages** — `domain_guide(domain: "pages")`
+- **New partials** — `domain_guide(domain: "partials")`
+- **GraphQL ops** — `domain_guide(domain: "graphql")`
+- **Any new domain** — `domain_guide(domain: "", section: "gotchas")`
+
+### MUST NOT
+
+- Use `{% include %}` for app code — deprecated. Use `{% render %}` or
+  `{% function %}`.
+- Use Shopify objects (`shop`, `cart`, `customer`, `product`, `collection`). These
+  do not exist in platformOS.
+- Write hand-drafted files to disk without calling `validate_code` on the proposed
+  content first. (Scaffold-written files are exempt — they are pre-validated.)
+- Assume module call syntax from memory — call `module_info(name)` to get the
+  authoritative live-scan API surface.
+- Ignore `consult_before_writing` in a scaffold response. Every domain listed there
+  MUST be consulted via `domain_guide` before writing.
+
+### Session-start checklist
+
+Before your first tool call, the following are true:
+
+- [ ] `server_status` called — confirms LSP and indexes are ready, lists
+  `domain_guides` and `session_pending`.
+- [ ] `load_development_guide` called (this document) — re-read if you lose
+  context or are unsure which step comes next.
+- [ ] `project_map` called once for full project baseline.
+
+Proceed only when all three are checked.
+
+## 1. Technology Stack
+
+platformOS uses three primary technologies:
+- **Liquid** — server-side templating language
+- **GraphQL** — data operations (built-in queries/mutations only)
+- **YAML** — configuration for schemas, translations, and settings
+
+The underlying databases (PostgreSQL, ElasticSearch, Redis) MUST be accessed ONLY through GraphQL and Liquid. There is NO direct database access.
+
+platformOS does NOT provide public GraphQL endpoints for client-side access. All GraphQL operations MUST be executed server-side using the `{% graphql %}` Liquid tag.
+
+### Source of Truth
+
+The official platformOS documentation is the ONLY source of truth:
+
+| Resource | URL |
+|----------|-----|
+| Official Docs | documentation.platformos.com |
+| GraphQL Schema | documentation.platformos.com/api/graphql/schema |
+| Liquid Filters | documentation.platformos.com/api-reference/liquid/platformos-filters.md |
+| Liquid Tags | documentation.platformos.com/api-reference/liquid/platformos-tags.md |
+| Context Object | documentation.platformos.com/api-reference/liquid/platformos-objects.md |
+| Core Module | github.com/Platform-OS/pos-module-core (README) |
+| User Module | github.com/Platform-OS/pos-module-user (README) |
+| Common Styling | github.com/Platform-OS/pos-module-common-styling (README) |
+| Payments Module | github.com/Platform-OS/pos-module-payments (README) |
+| Payments Stripe | github.com/Platform-OS/pos-module-payments-stripe (README) |
+| Tests Module | github.com/Platform-OS/pos-module-tests (README) |
+| Migrations | documentation.platformos.com/developer-guide/data-import-export/migrating-data.md |
+
+You MUST NOT invent undocumented behaviors, APIs, configurations, or directory structures. When uncertain, consult documentation.
+
+---
+
+## 2. Directory Structure
+
+```
+project-root/
+├── app/
+│   ├── assets/                    # Static files (images, fonts, styles, scripts)
+│   ├── views/
+│   │   ├── pages/                 # Controllers — NO HTML here
+│   │   ├── layouts/               # Wrapper templates
+│   │   └── partials/              # Reusable template snippets
+│   ├── lib/
+│   │   ├── commands/              # Business logic (build → check → execute)
+│   │   ├── queries/               # Data retrieval wrappers
+│   │   ├── events/                # Event definitions
+│   │   └── consumers/             # Event handlers
+│   ├── schema/                    # Database table definitions (YAML)
+│   ├── graphql/                   # GraphQL query/mutation files
+│   ├── emails/                    # Email templates
+│   ├── smses/                     # SMS templates
+│   ├── api_calls/                 # Third-party API integrations
+│   ├── translations/              # i18n content (YAML)
+│   ├── authorization_policies/    # DO NOT USE — use pos-module-user
+│   ├── migrations/                # One-time migration scripts
+│   └── config.yml                 # Feature flags
+├── modules/                       # Downloaded/custom modules (READ-ONLY)
+└── .pos                           # Environment endpoints
+```
+
+All application files MUST reside in the `app/` directory. You MUST NOT create or modify application files outside `app/`.
+
+The `modules/` directory is READ-ONLY. You MUST NOT edit files in `modules/` — override via documented mechanisms only.
+
+### File Naming Conventions
+
+| Directory | Pattern | Example |
+|-----------|---------|---------|
+| Commands | `app/lib/commands//.liquid` | `app/lib/commands/questions/create.liquid` |
+| Queries | `app/lib/queries//.liquid` | `app/lib/queries/articles/find.liquid` |
+| Unit Tests | `app/lib/tests//_test.liquid` | `app/lib/tests/articles/create_test.liquid` |
+| Pages | `app/views/pages//.liquid` | `app/views/pages/posts/show.liquid` |
+| Partials | `app/views/partials//.liquid` | `app/views/partials/articles/card.liquid` |
+| Assets | `app/assets//` | `app/assets/images/logo.png` |
+| Translations | `app/translations/.yml` | `app/translations/en.yml` |
+
+### File Formats
+
+| Extension | Content-Type | URL |
+|-----------|--------------|-----|
+| `*.liquid` or `*.html.liquid` | `text/html` | `/path` |
+| `*.json.liquid` | `application/json` | `/path.json` |
+| `*.js.liquid` | `application/javascript` | `/path.js` |
+
+---
+
+## 3. Architecture Rules
+
+### Pages MUST Be Controllers
+
+Pages MUST contain NO HTML, JS, or CSS. Pages MUST ONLY fetch data and delegate to partials via `render`. Each page file MUST handle exactly ONE HTTP method.
+
+### Business Logic MUST Live in Commands
+
+All business logic MUST reside in `app/lib/commands/`. Pages MUST delegate to commands. Commands MUST follow the build → check → execute pattern.
+
+### Path Resolution
+
+- `{% render 'blog_posts/card' %}` → `app/views/partials/blog_posts/card.liquid`
+- `{% function r = 'commands/blog_posts/create' %}` → `app/lib/commands/blog_posts/create.liquid`
+- `{% function r = 'queries/blog_posts/search' %}` → `app/lib/queries/blog_posts/search.liquid`
+
+The `lib/` prefix is implicit in `function` calls — do NOT include it.
+
+### Separation of Concerns
+
+- UI (Liquid templates) MUST be in partials and layouts
+- Data operations (GraphQL) MUST be in query/mutation files
+- Logic (commands) MUST be in `app/lib/commands/`
+
+### Modules First
+
+Every new feature MUST be built on top of existing platformOS modules (Core, User, Common-Styling, Test). You MUST NOT create duplicate models or authentication logic.
+
+### Generators First (DEPRECATED — DO NOT USE)
+
+You MUST prefer `pos-cli` generators (`generators-list`, `generators-run`) over manual file creation when available.
+
+---
+
+## 4. Pages
+
+Pages are controllers — they handle routing, fetch data, and delegate to partials.
+
+### Front Matter
+
+```liquid
+---
+slug: products/:id
+method: post
+layout: application
+metadata:
+  title: "Product Details"
+---
+```
+
+| Property | Default | Notes |
+|----------|---------|-------|
+| `slug` | From file path | Supports `:param`, `*wildcard`, `(/:optional)` |
+| `method` | `get` | `get`, `post`, `put`, `delete` |
+| `layout` | `application` | Empty string for no layout |
+
+**You MUST NOT use `authorization_policies` in front matter — use User Module helpers instead.**
+**For the home page (root /), omit the slug entirely — app/views/pages/index.liquid serves / by default.**
+**For the home page omit method as it can only be `get` which is default.**
+**One REST method per page**
+
+### Dynamic Routes
+
+| Pattern | URL | `context.params` |
+|---------|-----|------------------|
+| `products/:id` | `/products/123` | `{ "id": "123" }` |
+| `files/*path` | `/files/a/b.txt` | `{ "path": "a/b.txt" }` |
+| `search(/:q)` | `/search/books` | `{ "q": "books" }` |
+
+### REST CRUD Convention
+
+| HTTP Method | URL Slug | Page File | GraphQL | Purpose |
+|-------------|----------|-----------|---------|---------|
+| GET | `/posts/new` | `pages/posts/new.liquid` | — | Render create form |
+| POST | `/posts` | `pages/posts/create.liquid` | `record_create` | Persist new resource |
+| GET | `/posts/:id` | `pages/posts/show.liquid` | find query | Show single resource |
+| GET | `/posts/:id/edit` | `pages/posts/edit.liquid` | find query | Render edit form |
+| PUT/PATCH | `/posts/:id` | `pages/posts/update.liquid` | `record_update` | Update resource |
+| DELETE | `/posts/:id` | `pages/posts/delete.liquid` | `record_delete` | Delete resource |
+| GET | `/posts` | `pages/posts/index.liquid` | search query | List resources |
+
+### CSRF Protection
+
+Non-GET requests require a CSRF token. Without it, the platform cannot authenticate the request (user module queries return anonymous).
+
+### GET Page Example
+
+```liquid
+---
+slug: articles/:id
+method: get
+---
+{% liquid
+  function article = 'queries/articles/find', id: context.params.id
+
+  if article == blank
+    render '404'
+    break
+  endif
+
+  render 'articles/show', article: article
+%}
+```
+
+### POST Page Example
+
+```liquid
+---
+slug: articles
+method: post
+---
+{% liquid
+  function result = 'commands/articles/create', object: context.params.article
+
+  if result.valid
+    function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.articles.created', from: context.location.pathname
+    redirect_to '/articles'
+  else
+    render 'articles/new', result: result
+  endif
+%}
+```
+
+---
+
+## 5. Partials & Layouts
+
+### Partials
+
+Partials MUST NOT contain hardcoded user-facing text — always use translations (`{{ 'app.key' | t }}`).
+
+Partials MUST NOT have underscore-prefixed filenames.
+
+The render path maps: `render 'path/name'` → `app/views/partials/path/name.liquid`.
+
+### Layouts
+
+The default layout is `application`. Set `layout: ""` (empty string) in front matter for no layout.
+
+---
+
+## 6. Commands (Business Logic)
+
+All business logic MUST be encapsulated in commands following the build → check → execute pattern.
+
+### Main Command
+
+```liquid
+{% doc %}
+  @param object {object} - Article data
+{% enddoc %}
+
+{% liquid
+  function object = 'commands/articles/create/build', object: object
+  function object = 'commands/articles/create/check', object: object
+
+  if object.valid
+    function object = 'modules/core/commands/execute', mutation_name: 'articles/create', selection: 'record', object: object
+  endif
+
+  return object
+%}
+```
+
+### Build Stage
+
+Normalizes and structures input data:
+
+```liquid
+{% doc %}
+  @param object {object} - form params
+{% enddoc %}
+
+{% liquid
+  assign object['title'] = object.title
+  assign object['body'] = object.body
+
+  return object
+%}
+```
+
+### Check Stage
+
+Validates the built object:
+
+```liquid
+{% doc %}
+  @param object {object} - form params
+{% enddoc %}
+
+{% liquid
+  assign c = '{ "errors": {}, "valid": true }' | parse_json
+
+  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title'
+  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body'
+
+  assign object = object | hash_merge: valid: c.valid, errors: c.errors
+
+  return object
+%}
+```
+
+### ~~Alternative Core Module Syntax~~ (DEPRECATED — DO NOT USE)
+
+> **Warning:** `modules/core/commands/build` and `modules/core/commands/check` do NOT exist in the core module. Only `modules/core/commands/execute` is a shared core command. Build and check MUST be per-model files (e.g., `commands/articles/create/build.liquid`, `commands/articles/create/check.liquid`).
+
+```liquid
+{% comment %} WRONG — these partials do not exist: {% endcomment %}
+{% function object = 'modules/core/commands/build', object: object %}
+{% function object = 'modules/core/commands/check', object: object,
+  validators: '[{"name": "presence", "property": "title"}]'
+%}
+
+{% comment %} CORRECT — only execute is shared: {% endcomment %}
+{% if object.valid %}
+  {% function object = 'modules/core/commands/execute',
+    mutation_name: 'products/create', selection: 'record', object: object
+  %}
+{% endif %}
+
+{% return object %}
+```
+
+### Events
+
+```liquid
+{% comment %} Publish an event {% endcomment %}
+{% function _ = 'modules/core/commands/events/publish', type: 'order_created', object: order %}
+
+{% comment %} Consumer: app/lib/consumers/order_created/send_email.liquid {% endcomment %}
+{% graphql _ = 'emails/send_confirmation', email: event.object.email %}
+```
+
+All inputs MUST be validated in commands before persisting.
+
+---
+
+## 7. GraphQL
+
+GraphQL MUST be called from pages, query wrappers (`app/lib/queries/`), or commands (via `modules/core/commands/execute`). You MUST NOT call GraphQL from partials/views. Raw GraphQL MUST NOT appear in pages — use `.graphql` files exclusively.
+
+### Query Wrapper Pattern
+
+```liquid
+{% doc %}
+  @param id {string} - Article ID
+{% enddoc %}
+
+{% liquid
+  graphql result = 'articles/find', id: id
+  return result.records.results | first
+%}
+```
+
+### Search with Pagination
+
+```graphql
+query search($page: Int = 1, $keyword: String) {
+  records(
+    page: $page
+    per_page: 20
+    filter: {
+      table: { value: "article" }
+      properties: [{ name: "title", contains: $keyword }]
+    }
+    sort: { created_at: { order: DESC } }
+  ) {
+    total_pages
+    results {
+      id
+      title: property(name: "title")
+      body: property(name: "body")
+    }
+  }
+}
+```
+
+All list queries MUST support `per_page` and `page` arguments for pagination.
+
+### Find by ID
+
+```graphql
+query find($id: ID!) {
+  records(
+    per_page: 1
+    filter: {
+      id: { value: $id }
+      table: { value: "article" }
+    }
+  ) {
+    results {
+      id
+      title: property(name: "title")
+    }
+  }
+}
+```
+
+### Related Records (Avoids N+1)
+
+```graphql
+results {
+  id
+  # belongs-to (single)
+  author: related_record(table: "user", join_on_property: "user_id") {
+    email
+  }
+  # has-many
+  comments: related_records(table: "comment", join_on_property: "id", foreign_property: "article_id") {
+    body: property(name: "body")
+  }
+}
+```
+
+### Upload Property
+
+```graphql
+image: property_upload(name: "image") { url }
+```
+
+### Mutations
+
+All mutations MUST alias the result as `record:` so `modules/core/commands/execute` can extract it with `selection: 'record'`:
+
+- `record: record_create(record: { table: "...", properties: [...] }) { id }`
+- `record: record_update(id: $id, record: { properties: [...] }) { id }`
+- `record: record_delete(table: "...", id: $id) { id }` — **`table` is required**, without it: runtime error "You must specify table"
+
+### Pagination Component
+
+```liquid
+{% graphql result = 'products/search', page: context.params.page %}
+{% render 'modules/common-styling/pagination', total_pages: result.records.total_pages %}
+```
+
+---
+
+## 8. Schema
+
+Schema files define database tables in YAML at `app/schema/`.
+
+```yaml
+# app/schema/article.yml
+name: article
+properties:
+  - name: title
+    type: string
+  - name: body
+    type: text
+  - name: published_at
+    type: datetime
+  - name: image
+    type: upload
+    options:
+      acl: public
+```
+
+### Property Types
+
+`string`, `text`, `integer`, `float`, `boolean`, `datetime`, `date`, `array`, `upload`
+
+---
+
+## 9. Liquid Reference
+
+### Tags
+
+```liquid
+{% graphql result = 'query_name', arg: value %}
+{% function result = 'path/to/partial', arg: value %}
+{% render 'partial', var: value %}
+{% doc %} @param name {Type} - description {% enddoc %}
+{% return result %}
+{% export my_var, namespace: 'my_ns' %}
+{% parse_json data %}{"key": "value"}{% endparse_json %}
+{% redirect_to '/path', status: 302 %}
+{% session key = value %}
+{% log variable, type: 'debug' %}
+{% cache 'key', expire: 3600 %}...{% endcache %}
+{% background source_name: 'job_name', priority: 'low' %}...{% endbackground %}
+{% content_for_layout %}
+{% theme_render_rc 'modules/common-styling/toasts' %}
+```
+
+**`include` is DEPRECATED** — use `render` (UI partials) or `function` (logic partials) instead. Some module APIs still use `include` as their calling convention (follow those docs as-is).
+
+### Output
+
+```liquid
+{{ variable }}              
+{{ variable | html_safe }}  
+{% print variable %}        
+```
+
+### Common Filters
+
+- **Arrays:** `array_add`, `array_map`, `array_sort_by`, `array_group_by`
+- **Hashes:** `hash_merge`, `hash_dig`, `hash_keys`
+- **Dates:** `add_to_time`, `localize`, `is_date_in_past`
+- **Validation:** `is_email_valid`, `is_json_valid`
+- **Encoding:** `json`, `base64_encode`, `url_encode`
+
+### Coding Standards
+
+You MUST NOT line-wrap statements within `{% liquid %}` blocks. Each statement MUST be on a single line.
+
+**Correct:**
+```liquid
+{% liquid
+  assign filtered = products | where: 'available', true | map: 'title' | first
+  assign price = product | where: 'id', pid | map: 'price' | first
+%}
+```
+
+**WRONG (causes syntax errors):**
+```liquid
+{% liquid
+  assign filtered = products
+    | where: 'available', true
+    | map: 'title'
+    | first
+%}
+```
+
+---
+
+## 10. Global Context
+
+**All global objects MUST use the `context.` prefix.** Using bare names (e.g., `params` instead of `context.params`, `page` instead of `context.page`) will fail silently or produce wrong results.
+
+| Property | Description |
+|----------|-------------|
+| `context.params` | HTTP parameters (query string + body) |
+| `context.session` | Server-side session storage |
+| `context.location` | URL info (`pathname`, `search`, `host`) |
+| `context.environment` | `staging` or `production` |
+| `context.is_xhr` | `true` for AJAX requests |
+| `context.authenticity_token` | CSRF token |
+| `context.constants` | Environment constants (hidden from `{{ context }}` for security) |
+| `context.page.metadata` | Page metadata from front matter |
+
+You MUST NOT use `context.current_user` directly — always use `modules/user/queries/user/current`.
+
+---
+
+## 11. User Module (Authentication & Authorization)
+
+You MUST use the User Module for all authentication and authorization. You MUST NOT use `authorization_policies/` directly. You MUST NOT duplicate login logic. You MUST NOT customize auth routes unless explicitly requested.
+
+### Built-in Roles
+
+- **Anonymous** — unauthenticated users
+- **Authenticated** — any logged-in user
+- **Superadmin** — bypasses ALL permission checks
+
+### Authorization Helpers
+
+```liquid
+{% function profile = 'modules/user/queries/user/current' %}
+
+{% comment %} Check permission (returns true/false) {% endcomment %}
+{% function can = 'modules/user/helpers/can_do', requester: profile, do: 'article.create' %}
+
+{% comment %} Enforce permission (403 if denied) — uses include (module API convention) {% endcomment %}
+{% include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'admin.view', redirect_anonymous_to_login: true %}
+
+{% comment %} Redirect if denied — uses include (module API convention) {% endcomment %}
+{% include 'modules/user/helpers/can_do_or_redirect', requester: profile, do: 'orders.view', return_url: '/login' %}
+```
+
+> Note: These auth helpers use `include` because they need access to the caller's scope to halt execution. This is the module's documented API — do not replace with `render` or `function`.
+
+### Custom Permissions
+
+Override `modules/user/public/lib/queries/role_permissions/permissions.liquid`:
+
+```bash
+mkdir -p app/modules/user/public/lib/queries/role_permissions
+cp modules/user/public/lib/queries/role_permissions/permissions.liquid \
+   app/modules/user/public/lib/queries/role_permissions/permissions.liquid
+```
+
+Define roles:
+```liquid
+{% parse_json data %}
+{
+  "admin": ["admin.view", "users.manage"],
+  "editor": ["article.create", "article.update"],
+  "superadmin": []
+}
+{% endparse_json %}
+{% return data %}
+```
+
+---
+
+## 12. Core Module
+
+You MUST use pos-module-core for commands, events, and validators.
+
+---
+
+## 13. Common Styling
+
+You MUST NOT use Tailwind, Bootstrap, or custom CSS frameworks. You MUST use `pos-*` prefixed classes from the common-styling module. Check `/style-guide` on your instance for available components.
+
+### Setup
+
+```liquid
+{% comment %} In  {% endcomment %}
+{% render 'modules/common-styling/init' %}
+```
+```html
+
+```
+
+### File Upload Component
+
+```liquid
+{% render 'modules/common-styling/forms/upload',
+  id: 'image', presigned_upload: presigned, name: 'image',
+  allowed_file_types: ['image/*'], max_number_of_files: 5
+%}
+```
+
+---
+
+## 14. Translations (i18n)
+
+You MUST NOT hardcode user-facing text in partials. You MUST always use `{{ 'app.key' | t }}` and define translations in `app/translations/`.
+
+---
+
+## 15. Forms
+
+You MUST use HTML `` tags. You MUST NOT use `{% form %}`.
+
+Forms MUST include the CSRF token:
+```html
+
+```
+
+For PUT/DELETE, forms MUST use POST with a `_method` hidden field:
+```html
+
+  
+  
+  
+
+```
+
+Form fields MUST use bracket notation for resource binding:
+```html
+
+```
+
+Access in page: `context.params.resource`
+
+HTML forms submit checkbox values as \"on\" (string), but GraphQL expects boolean field to be Boolean type, not string.
+
+---
+
+## 16. Constants & Credentials
+
+You MUST NOT hardcode API keys, secrets, or environment-specific URLs. You MUST use `context.constants`.
+
+### Setting Constants
+
+**Via CLI:**
+```bash
+pos-cli constants set --name STRIPE_SK_KEY --value "sk_test_..." dev
+pos-cli constants set --name OPENAI_API_KEY --value "sk-..." dev
+pos-cli constants set --name API_BASE_URL --value "https://api.example.com" dev
+```
+
+**Via GraphQL:**
+```graphql
+mutation {
+  constant_set(name: "STRIPE_SK_KEY", value: "sk_test_...") {
+    name
+  }
+}
+```
+
+### Accessing Constants in Liquid
+
+Constants are hidden from `{{ context }}` for security. You MUST access them explicitly:
+```liquid
+{{ context.constants.STRIPE_SK_KEY }}
+{{ context.constants.API_BASE_URL }}
+```
+
+### Naming Conventions
+
+| Use Case | Example |
+|----------|---------|
+| API keys | `STRIPE_SK_KEY`, `OPENAI_API_KEY`, `TWILIO_API_SECRET` |
+| API URLs | `API_BASE_URL` |
+| Feature flags | `FEATURE_NEW_CHECKOUT_ENABLED` |
+
+Staging constants SHOULD be initialized in migrations so new developers and tests can use test credentials automatically.
+
+---
+
+## 17. Flash Messages & Toasts
+
+### Layout Setup (before ``)
+
+```liquid
+{% liquid
+  function flash = 'modules/core/commands/session/get', key: 'sflash'
+  if context.location.pathname != flash.from or flash.force_clear
+    function _ = 'modules/core/commands/session/clear', key: 'sflash'
+  endif
+  render 'modules/common-styling/toasts', params: flash
+%}
+```
+
+### Liquid Usage
+
+```liquid
+{% liquid
+  function _ = 'modules/core/commands/session/set', key: 'sflash', value: 'app.order.confirmed', from: context.location.pathname
+  redirect_to '/orders'
+%}
+```
+
+### JavaScript Usage
+
+```javascript
+new pos.modules.toast('success', 'Saved!');
+new pos.modules.toast('error', 'Failed');
+```
+
+---
+
+## 18. Notifications (Email/SMS)
+
+```liquid
+{% comment %} app/emails/order_confirmation.liquid {% endcomment %}
+---
+to: {{ data.email }}
+from: shop@example.com
+subject: "Order #{{ data.order_id }}"
+layout: mailer
+---
+
      Thank you for your order!
      
+```
+
+Emails SHOULD be sent asynchronously using events + consumers.
+
+---
+
+## 19. Payments (Stripe)
+
+### Install
+
+```bash
+pos-cli modules install payments && pos-cli modules install payments_stripe
+pos-cli constants set --name stripe_sk_key --value "sk_test_..." dev
+```
+
+### Create Transaction
+
+```liquid
+{% function transaction = 'modules/payments/commands/transactions/create',
+  gateway: 'stripe', email: email, line_items: items,
+  success_url: '/thank-you', cancel_url: '/cart'
+%}
+{% function url = 'modules/payments/queries/pay_url', transaction: transaction %}
+{% redirect_to url, status: 303 %}
+```
+
+Handle events via consumers: `payments_transaction_succeeded`, `payments_transaction_failed`
+
+**Test card:** `4242 4242 4242 4242`, any future date, any CVC.
+
+---
+
+## 20. Migrations
+
+Migrations execute code outside the regular application cycle — useful for seeding data, initializing constants, and database modifications.
+
+### File Structure
+
+```
+app/migrations/
+├── 20240115120000_seed_initial_data.liquid
+├── 20240116093000_add_default_categories.liquid
+└── 20240120150000_init_staging_constants.liquid
+```
+
+Files MUST be named with UTC timestamp prefix for chronological execution.
+
+### Creating a Migration
+
+```bash
+pos-cli migrations generate dev init_staging_constants
+# Creates: app/migrations/YYYYMMDDHHMMSS_init_staging_constants.liquid
+```
+
+### Example: Initialize Staging Constants
+
+```liquid
+{% liquid
+  if context.environment == 'staging'
+    graphql _ = 'constants/set', name: 'STRIPE_SK_KEY', value: 'sk_test_example123'
+    graphql _ = 'constants/set', name: 'API_BASE_URL', value: 'https://api-staging.example.com'
+  endif
+%}
+```
+
+### Example: Seed Data
+
+```liquid
+{% parse_json categories %}
+["Electronics", "Clothing", "Books"]
+{% endparse_json %}
+
+{% for category in categories %}
+  {% graphql _ = 'categories/create', name: category %}
+{% endfor %}
+```
+
+### Running Migrations
+
+- **Automatic:** Pending migrations run on `pos-cli deploy`
+- **Manual:** `pos-cli migrations run TIMESTAMP dev`
+
+### Migration States
+
+- **pending** — not yet executed (runs on next deploy)
+- **done** — successfully completed (will not run again)
+- **error** — failed (can edit and retry)
+
+For large data imports, use Data Import/Export instead of migrations.
+
+---
+
+## 21. Testing
+
+Tests MUST go in `app/lib/tests/*_test.liquid`. Testing ONLY works in staging/development.
+
+Every new feature MUST have unit tests for commands.
+
+```liquid
+{% function result = 'commands/products/create', title: "Test" %}
+{% function contract = 'modules/tests/assertions/valid_object', contract: contract, object: result %}
+{% function contract = 'modules/tests/assertions/equal', contract: contract, given: result.title, expected: "Test" %}
+{% return contract %}
+```
+
+Run tests: `/_tests/run` in browser, or `pos-cli test run staging` for CI.
+
+---
+
+## 22. CLI Commands
+
+```bash
+# Deployment
+pos-cli deploy dev
+
+# Sync (MUST sync every file after modification)
+pos-cli sync dev
+
+# Logs
+pos-cli logs dev
+
+# Linting (MUST run after EVERY file change)
+platformos-check
+
+# Run Liquid inline
+pos-cli exec liquid dev ''
+
+# Run GraphQL inline
+pos-cli exec graphql dev ''
+
+# Tests
+pos-cli test run staging
+
+# Modules
+pos-cli modules install 
+pos-cli modules download 
+
+# Constants
+pos-cli constants set --name KEY --value "value" dev
+
+# Generate CRUD
+pos-cli generate run modules/core/generators/crud   --include-views
+
+# Migrations
+pos-cli migrations generate dev 
+pos-cli migrations run TIMESTAMP dev
+```
+
+---
+
+## 23. Modules Reference
+
+| Module | Install | Purpose | Required |
+|--------|---------|---------|----------|
+| `core` | Required | Commands, events, validators | YES |
+| `user` | Required | Auth, RBAC, OAuth2 | YES |
+| `common-styling` | Required | CSS, components | YES |
+| `tests` | Optional | Testing framework | YES (for testing) |
+| `payments` + `payments_stripe` | Optional | Stripe payments | No |
+| `chat` | Optional | WebSocket messaging | No |
+| `openai` | Optional | OpenAI integration | No |
+
+---
+
+## 24. Forbidden Behaviors
+
+You MUST NOT:
+- Edit files in `./modules/` (read-only)
+- Break long lines in `{% liquid %}` blocks (causes syntax errors)
+- Invent Liquid tags, filters, or GraphQL types that do not exist
+- Use `{% form %}` tag (use HTML `
      ` only)
+- Bypass security (CSRF tokens, authorization)
+- Access databases directly outside GraphQL
+- Deploy without running `platformos-check`
+- Sync files outside `./app/`
+- Use `authorization_policies/` directly (use pos-module-user)
+- Use `context.current_user` directly (use user module queries)
+- Use Tailwind, Bootstrap, or custom CSS frameworks (use common-styling)
+- Hardcode API keys, secrets, or environment-specific URLs
+- Hardcode user-facing text in partials (use translations)
+- Put HTML, JS, or CSS in page files
+- Call GraphQL from partials
+- Put raw GraphQL in pages (use `.graphql` files)
+- Create or modify application files outside the `app/` directory
+- Use more than one HTTP methods per page:
+```
+#Never try to handle POST + rendering + redirect in the same root page. Keep it clean:
+/ → GET → renders page
+/contact (or similar) → POST → processes + redirects
+```
+- Set main page methos as POST - it is not PHP!
+
+---
+
+## 25. Pre-Flight Checklist
+
+Before every change, verify:
+
+- [ ] No underscore prefix in partial filenames
+- [ ] `render 'path/name'` maps to `app/views/partials/path/name.liquid`
+- [ ] Pages have ONE HTTP method each
+- [ ] No raw GraphQL in pages (use `{% graphql %}` tag with `.graphql` files)
+- [ ] No HTML/JS/CSS in pages
+- [ ] No hardcoded text in partials (use translations)
+- [ ] `platformos-check` passes with 0 errors
+- [ ] Every file synced after modification
+- [ ] All list queries support pagination (`per_page`, `page`)
+- [ ] All inputs validated in commands before persisting
+- [ ] CSS/JS minified, `asset_url` used for cache busting
+
+### Asset URL Usage
+
+```liquid
+{{ 'images/img.png' | asset_url }}
+```
diff --git a/src/http-server.js b/src/http-server.js
index 133aae8..234eb28 100644
--- a/src/http-server.js
+++ b/src/http-server.js
@@ -390,19 +390,127 @@ function handleGetKnowledge(dataRoot, res) {
   }
 }
 
+/**
+ * Two coexisting hint subsystems are joined here:
+ *   • static  — `src/data/hints/.md` rendered into the diagnostic by
+ *               error-enricher.js. Legacy LSP checks; one fixed blob each.
+ *   • rule    — `src/core/rules/.js` builds the hint dynamically per
+ *               diagnostic. No md file exists; the registry is the source.
+ *
+ * Pre-fix the endpoint only knew about (1) and 404'd on every (2). The
+ * dashboard drilldown silently broke for the 12+ rule-driven checks
+ * (GraphQLVariablesCheck, PartialCallArguments, NonGetRenderingPage, …).
+ *
+ * Response shape:
+ *   GET /api/hints
+ *     { hints: [name, …],            // backward-compat: union of both kinds
+ *       checks: [{ name, sources: ['static'|'rule', …] }, …] }
+ *   GET /api/hints?name=
+ *     { name, content, source: 'static' }                              // md found
+ *     { name, content, source: 'rule', rule_ids: [...] }               // synthesized from registry
+ *     404 only when both lookups miss.
+ */
 function handleGetHints(dataRoot, url, res) {
   if (!dataRoot) return sendJson(res, 503, { error: 'Data dir not available' });
   const hintsDir = join(dataRoot, 'hints');
   const name = url.searchParams.get('name');
+
+  // Populate the rule registry once. Idempotent — guarded by `_loaded`.
+  loadAllRules();
+
+  if (name) {
+    const file = join(hintsDir, `${name}.md`);
+    if (existsSync(file)) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        return sendJson(res, 200, { name, content, source: 'static' });
+      } catch (e) {
+        // Fall through — let the rule registry resolve it if possible.
+      }
+    }
+    const rules = getRulesForCheck(name);
+    if (rules.length > 0) {
+      return sendJson(res, 200, {
+        name,
+        content: synthesizeRuleHintDoc(name, rules),
+        source: 'rule',
+        rule_ids: rules.map(r => r.id),
+      });
+    }
+    return sendJson(res, 404, { error: `No hint or rule for ${name}` });
+  }
+
+  let staticNames = [];
   try {
-    if (name) {
-      const content = readFileSync(join(hintsDir, `${name}.md`), 'utf-8');
-      return sendJson(res, 200, { name, content });
+    staticNames = readdirSync(hintsDir).filter(f => f.endsWith('.md')).map(f => f.replace('.md', ''));
+  } catch {
+    // hints dir may be missing on a fresh checkout — still return rule names.
+  }
+  const ruleNames = getAllChecksWithRules();
+  const staticSet = new Set(staticNames);
+  const ruleSet = new Set(ruleNames);
+  const all = Array.from(new Set([...staticNames, ...ruleNames])).sort();
+  const checks = all.map(n => {
+    const sources = [];
+    if (staticSet.has(n)) sources.push('static');
+    if (ruleSet.has(n)) sources.push('rule');
+    return { name: n, sources };
+  });
+  sendJson(res, 200, { hints: all, checks });
+}
+
+/**
+ * Render a markdown reference doc for a rule-driven check by introspecting
+ * the registry. Lists each sub-rule with its priority and the source of its
+ * `when()` predicate (truncated). Surfaces the file path the developer must
+ * edit to change the hint at runtime.
+ */
+function synthesizeRuleHintDoc(name, rules) {
+  const sorted = [...rules].sort((a, b) => a.priority - b.priority);
+  const moduleBase = name.replace(/^pos-supervisor:/, '');
+  const lines = [];
+  lines.push(`# ${name}`);
+  lines.push('');
+  lines.push(
+    `*Rule-driven check.* Hints are generated dynamically by ` +
+    `\`src/core/rules/${moduleBase}.js\` at validation time. There is no static ` +
+    `\`.md\` for this check — agents see whatever \`apply()\` returns from the ` +
+    `first matching sub-rule below.`
+  );
+  lines.push('');
+  lines.push(`## Sub-rules (${sorted.length})`);
+  lines.push('');
+  lines.push('Engine returns the first match in priority order (lower = higher priority).');
+  lines.push('');
+  for (const r of sorted) {
+    lines.push(`### \`${r.id}\` — priority ${r.priority}`);
+    lines.push('');
+    const whenSrc = stringifyRulePredicate(r.when);
+    if (whenSrc) {
+      lines.push('```js');
+      lines.push(`when: ${whenSrc}`);
+      lines.push('```');
+      lines.push('');
     }
-    const files = readdirSync(hintsDir).filter(f => f.endsWith('.md')).map(f => f.replace('.md', ''));
-    sendJson(res, 200, { hints: files });
-  } catch (e) {
-    sendJson(res, 404, { error: e.message });
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push(
+    `To change the hint shown to agents, edit the relevant \`apply()\` in ` +
+    `\`src/core/rules/${moduleBase}.js\`. Each \`apply()\` returns ` +
+    `\`{ rule_id, hint_md, fixes, confidence, see_also? }\` which the validator ` +
+    `embeds into the diagnostic.`
+  );
+  return lines.join('\n');
+}
+
+function stringifyRulePredicate(fn) {
+  if (typeof fn !== 'function') return null;
+  try {
+    const src = fn.toString();
+    return src.length > 240 ? `${src.slice(0, 237)}...` : src;
+  } catch {
+    return null;
   }
 }
 
diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js
index a71293d..6a30c38 100644
--- a/src/tools/validate-code.js
+++ b/src/tools/validate-code.js
@@ -241,6 +241,7 @@ explicitly only if you are validating a file that is NOT part of the most recent
           content,
           factGraph,
           filePath: file_path,
+          projectDir: ctx.directory,
         };
 
         // Enrich all diagnostics in both quick and full modes.
@@ -755,6 +756,7 @@ explicitly only if you are validating a file that is NOT part of the most recent
           tagsIndex: ctx.tagsIndex,
           schemaIndex: ctx.schemaIndex,
           analyticsStore: ctx.analyticsStore,
+          projectDir: ctx.directory,
         });
       } catch { /* bridge is best-effort — fall through to default stamping */ }
 
diff --git a/tests/integration/analytics/structural-rule-attribution.test.js b/tests/integration/analytics/structural-rule-attribution.test.js
index 591cb7d..17818f6 100644
--- a/tests/integration/analytics/structural-rule-attribution.test.js
+++ b/tests/integration/analytics/structural-rule-attribution.test.js
@@ -53,8 +53,10 @@ function readValidatorEmits(projectDir) {
 describe('structural rule attribution via bridge', () => {
   // A page with method: post + HTML body — exactly the NonGetRenderingPage
   // trigger. No slug under /api/, renders inline HTML and interpolates a
-  // variable so the UI-signal heuristics match.
-  it('NonGetRenderingPage lands as "NonGetRenderingPage.default", not ".unmatched"', async () => {
+  // variable so the UI-signal heuristics match. After task-4's three-subrule
+  // split (html_on_post / api_renders_html / get_form_target) this case
+  // routes to `html_on_post` rather than the catch-all `.default`.
+  it('NonGetRenderingPage lands as a specific subrule via the bridge, not ".unmatched"', async () => {
     const FILE = 'app/views/pages/ngrp-bridge-test.liquid';
     const CONTENT = '---\nslug: ngrp-bridge-test\nmethod: post\nlayout: application\n---\n
      form
      \n{{ x }}\n';
 
@@ -69,7 +71,8 @@ describe('structural rule attribution via bridge', () => {
     const emits = readValidatorEmits(proj.dir);
     const ngrp = emits.find(e => e.file === FILE && e.check === 'pos-supervisor:NonGetRenderingPage');
     expect(ngrp).toBeDefined();
-    expect(ngrp.hint_rule_id).toBe('NonGetRenderingPage.default');
+    // Non-API slug + HTML body + non-GET method → html_on_post subrule.
+    expect(ngrp.hint_rule_id).toBe('NonGetRenderingPage.html_on_post');
     // Confidence also propagates through the bridge.
     expect(ngrp.confidence).toBe(0.9);
   });
diff --git a/tests/unit/error-enricher-bridge.test.js b/tests/unit/error-enricher-bridge.test.js
index 7257741..e4ce8c4 100644
--- a/tests/unit/error-enricher-bridge.test.js
+++ b/tests/unit/error-enricher-bridge.test.js
@@ -39,6 +39,10 @@ const ctx = {
 };
 
 describe('bridgeRulesOntoUnattributed', () => {
+  // Task-4 split NonGetRenderingPage into three subrules
+  // (html_on_post / api_renders_html / get_form_target). The bridge must
+  // pick the subrule whose discriminator regex matches the structural
+  // emit's message — not the catch-all default.
   test('applies registered rule to a structural diagnostic with no prior rule_id', () => {
     registerRules(NonGetRenderingPageRules);
     const result = {
@@ -46,14 +50,14 @@ describe('bridgeRulesOntoUnattributed', () => {
       warnings: [{
         check: 'pos-supervisor:NonGetRenderingPage',
         severity: 'warning',
-        message: 'method: post + renders HTML',
+        message: 'Page has `method: post` but renders HTML (layout, partials, or `{{ ... }}` output).',
         line: 1,
       }],
       infos: [],
     };
     bridgeRulesOntoUnattributed(result, ctx);
     const w = result.warnings[0];
-    expect(w.rule_id).toBe('NonGetRenderingPage.default');
+    expect(w.rule_id).toBe('NonGetRenderingPage.html_on_post');
     expect(w.confidence).toBe(0.9);
     expect(w.hint).toMatch(/method: post/i);
   });
diff --git a/tests/unit/http-server.test.js b/tests/unit/http-server.test.js
index ae29f88..776bfba 100644
--- a/tests/unit/http-server.test.js
+++ b/tests/unit/http-server.test.js
@@ -96,6 +96,95 @@ describe('HTTP GET endpoints', () => {
   });
 });
 
+describe('HTTP GET /api/hints', () => {
+  it('list mode returns both static md hints and rule-driven check names', async () => {
+    const { status, body } = await httpGet('/api/hints');
+    expect(status).toBe(200);
+    expect(Array.isArray(body.hints)).toBe(true);
+    expect(Array.isArray(body.checks)).toBe(true);
+
+    // Legacy md hints — sample from src/data/hints/
+    expect(body.hints).toContain('GraphQLCheck');
+    // Rule-driven (no md file) — must be present after the fix.
+    expect(body.hints).toContain('GraphQLVariablesCheck');
+    expect(body.hints).toContain('PartialCallArguments');
+
+    // Per-check sources metadata
+    const gqlVars = body.checks.find(c => c.name === 'GraphQLVariablesCheck');
+    expect(gqlVars).toBeDefined();
+    expect(gqlVars.sources).toContain('rule');
+    expect(gqlVars.sources).not.toContain('static');
+
+    const gqlCheck = body.checks.find(c => c.name === 'GraphQLCheck');
+    expect(gqlCheck).toBeDefined();
+    expect(gqlCheck.sources).toContain('static');
+  });
+
+  it('GET ?name= returns md content with source=static', async () => {
+    const { status, body } = await httpGet('/api/hints?name=GraphQLCheck');
+    expect(status).toBe(200);
+    expect(body.name).toBe('GraphQLCheck');
+    expect(body.source).toBe('static');
+    expect(typeof body.content).toBe('string');
+    expect(body.content.length).toBeGreaterThan(20);
+  });
+
+  // Repro for the dashboard 404 reported on 2026-04-28: rule-driven checks
+  // had no md file, the endpoint 404'd, drilldown showed "Failed to load".
+  it('GET ?name=GraphQLVariablesCheck synthesizes a rule doc instead of 404', async () => {
+    const { status, body } = await httpGet('/api/hints?name=GraphQLVariablesCheck');
+    expect(status).toBe(200);
+    expect(body.name).toBe('GraphQLVariablesCheck');
+    expect(body.source).toBe('rule');
+    expect(Array.isArray(body.rule_ids)).toBe(true);
+    // Sub-rule ids must be present in the synthesized doc.
+    expect(body.rule_ids).toContain('GraphQLVariablesCheck.required');
+    expect(body.rule_ids).toContain('GraphQLVariablesCheck.unknown');
+    expect(body.rule_ids).toContain('GraphQLVariablesCheck.parser_blind_spot');
+    expect(body.content).toContain('GraphQLVariablesCheck');
+    expect(body.content).toContain('Rule-driven');
+    expect(body.content).toContain('src/core/rules/GraphQLVariablesCheck.js');
+    // Each sub-rule must be documented with priority + when() source.
+    expect(body.content).toContain('parser_blind_spot');
+    expect(body.content).toContain('priority');
+  });
+
+  it('GET ?name= still 404s when neither md nor rule exists', async () => {
+    const { status, body } = await httpGet('/api/hints?name=NoSuchCheckEverDefined');
+    expect(status).toBe(404);
+    expect(body.error).toBeDefined();
+  });
+
+  it('GET ?name= resolves prefixed rule-driven checks', async () => {
+    // pos-supervisor:InvalidLayout is registered with the prefix, has no md
+    // file, and the dashboard splits on the first dot when computing
+    // baseCheck — so the colon prefix must round-trip cleanly.
+    const { status, body } = await httpGet(
+      '/api/hints?name=' + encodeURIComponent('pos-supervisor:InvalidLayout')
+    );
+    expect(status).toBe(200);
+    expect(body.source).toBe('rule');
+    expect(body.name).toBe('pos-supervisor:InvalidLayout');
+    // Module path strips the `pos-supervisor:` prefix when we point at the
+    // file the developer must edit — the rule files are not namespaced.
+    expect(body.content).toContain('src/core/rules/InvalidLayout.js');
+  });
+
+  it('GET ?name= with both md and rule prefers static md', async () => {
+    // pos-supervisor:NonGetRenderingPage has BOTH a md file and a rule
+    // module. The endpoint must serve the md (legacy enricher path is what
+    // agents actually consume) and the rule sub-rules remain reachable via
+    // the per-check rule_ids list elsewhere in the dashboard.
+    const { status, body } = await httpGet(
+      '/api/hints?name=' + encodeURIComponent('pos-supervisor:NonGetRenderingPage')
+    );
+    expect(status).toBe(200);
+    expect(body.source).toBe('static');
+    expect(typeof body.content).toBe('string');
+    expect(body.content.length).toBeGreaterThan(20);
+  });
+});
+
 describe('HTTP POST /call', () => {
   it('executes domain_guide tool', async () => {
     const { status, body } = await httpPost('/call', {
diff --git a/tests/unit/liquid-parser.test.js b/tests/unit/liquid-parser.test.js
index 063675b..a54df36 100644
--- a/tests/unit/liquid-parser.test.js
+++ b/tests/unit/liquid-parser.test.js
@@ -51,6 +51,66 @@ describe('extractAllFromAST', () => {
     expect(result.graphql[0].queryName).toBe('products/search');
   });
 
+  it('captures named-argument names and source_kind=tag for the canonical tag form', () => {
+    const ast = parseLiquidFile(
+      "{% graphql result = 'op', name: shaped.name, email: shaped.email %}"
+    );
+    const result = extractAllFromAST(ast);
+    expect(result.graphql).toHaveLength(1);
+    expect(result.graphql[0].args).toEqual(['name', 'email']);
+    expect(result.graphql[0].source_kind).toBe('tag');
+  });
+
+  it('classifies single-line graphql inside {% liquid %} block as liquid_inline', () => {
+    const ast = parseLiquidFile(
+      "{% liquid\ngraphql result = 'op', name: shaped.name, email: shaped.email\n%}"
+    );
+    const result = extractAllFromAST(ast);
+    expect(result.graphql).toHaveLength(1);
+    expect(result.graphql[0].args).toEqual(['name', 'email']);
+    expect(result.graphql[0].source_kind).toBe('liquid_inline');
+  });
+
+  // Repro for the DEMO regression spiral (2026-04-27): multi-line comma
+  // continuation inside `{% liquid %}` block. The liquid-html-parser truncates
+  // the call at the first newline — markup.args is empty, the args are
+  // silently dropped, and pos-cli's LSP fires "Required parameter X missing"
+  // for each. The classifier flags this so the rule layer can route to a
+  // syntax-fix hint instead of the misleading "add the arg" hint.
+  it('flags multi-line graphql in {% liquid %} block as liquid_multiline_truncated', () => {
+    const ast = parseLiquidFile(
+      "{% liquid\ngraphql result = 'op',\n  name: shaped.name,\n  email: shaped.email\n%}"
+    );
+    const result = extractAllFromAST(ast);
+    expect(result.graphql).toHaveLength(1);
+    expect(result.graphql[0].source_kind).toBe('liquid_multiline_truncated');
+    // Args extracted by markup.args are empty here (parser truncation) — the
+    // detector must not depend on args.length to distinguish the kind.
+    expect(result.graphql[0].args).toEqual([]);
+  });
+
+  it('does not flag a comma-ending inline call without trailing named-arg lines', () => {
+    // No `name:` continuation after — just a stray comma inside whatever
+    // followed in the liquid block. Should NOT be classified as truncated.
+    const ast = parseLiquidFile(
+      "{% liquid\ngraphql result = 'op', name: shaped.name,\nassign other = 1\n%}"
+    );
+    const result = extractAllFromAST(ast);
+    expect(result.graphql).toHaveLength(1);
+    expect(result.graphql[0].source_kind).toBe('liquid_inline');
+  });
+
+  it('upgrades source_kind to truncated when any duplicate call is truncated', () => {
+    const ast = parseLiquidFile(
+      "{% graphql a = 'op', name: x %}\n" +
+      "{% liquid\ngraphql b = 'op',\n  name: y,\n  email: z\n%}"
+    );
+    const result = extractAllFromAST(ast);
+    // Dedup keeps a single entry but the surface kind reflects the worst case.
+    expect(result.graphql).toHaveLength(1);
+    expect(result.graphql[0].source_kind).toBe('liquid_multiline_truncated');
+  });
+
   it('extracts filter names', () => {
     const ast = parseLiquidFile("{{ 'hello' | t }}\n{{ price | pricify | json }}");
     const result = extractAllFromAST(ast);
diff --git a/tests/unit/rules/DeprecatedTag.test.js b/tests/unit/rules/DeprecatedTag.test.js
new file mode 100644
index 0000000..31dcab5
--- /dev/null
+++ b/tests/unit/rules/DeprecatedTag.test.js
@@ -0,0 +1,122 @@
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+import { rules } from '../../../src/core/rules/DeprecatedTag.js';
+
+beforeEach(() => { clearRules(); registerRules(rules); });
+
+describe('DeprecatedTag rule (upstream LSP)', () => {
+  test('include subrule fires on params.tag', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'include', replacement: 'render' },
+      message: "Deprecated tag 'include': replaced by render",
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.include');
+    expect(result.hint_md).toContain('isolated scope');
+    expect(result.fixes[0].description).toContain('render');
+  });
+
+  test('hash_assign subrule fires on params.tag', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'hash_assign' },
+      message: "Deprecated tag 'hash_assign'",
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.hash_assign');
+    expect(result.hint_md).toContain('assign x["key"]');
+  });
+
+  test('parse_json subrule fires on params.tag', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'parse_json' },
+      message: "Deprecated tag 'parse_json'",
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.parse_json');
+    expect(result.hint_md).toContain('| parse_json');
+    expect(result.hint_md).toContain('capture');
+  });
+
+  test('falls through to default for unknown deprecated tag', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'foobar' },
+      message: "Deprecated tag 'foobar'",
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.default');
+  });
+
+  test('default rule reads tag/replacement from params when present', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'foobar', replacement: 'baz' },
+      message: 'irrelevant',
+    }, {});
+    expect(result.hint_md).toContain('`{% foobar %}`');
+    expect(result.hint_md).toContain('Use `{% baz %}` instead.');
+  });
+});
+
+describe('DeprecatedTag rule (pos-supervisor structural variant)', () => {
+  test('include subrule fires on raw message even without params.tag', () => {
+    // structural-warnings emits messages WITHOUT populating params.tag
+    // (no extractor for `pos-supervisor:DeprecatedTag` in diagnostic-record).
+    // The raw-message gate must catch it.
+    const result = runRules({
+      check: 'pos-supervisor:DeprecatedTag',
+      params: {},
+      message: '`{% include %}` is deprecated. Use `{% render %}` instead — render has isolated scope.',
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.include');
+  });
+
+  test('hash_assign subrule fires on raw message', () => {
+    const result = runRules({
+      check: 'pos-supervisor:DeprecatedTag',
+      params: {},
+      message: '`{% hash_assign %}` is deprecated. Use `{% assign var["key"] = "value" %}`.',
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.hash_assign');
+  });
+
+  test('parse_json subrule fires on raw message', () => {
+    const result = runRules({
+      check: 'pos-supervisor:DeprecatedTag',
+      params: {},
+      message: '`{% parse_json %}` is deprecated.',
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.parse_json');
+  });
+
+  test('default fires when no known tag matches', () => {
+    const result = runRules({
+      check: 'pos-supervisor:DeprecatedTag',
+      params: {},
+      message: '`{% future_tag %}` is deprecated.',
+    }, {});
+    expect(result.rule_id).toBe('DeprecatedTag.default');
+  });
+});
+
+describe('DeprecatedTag rule — guidance-only fix policy', () => {
+  test('every subrule emits a single guidance fix (heuristic owns text_edit)', () => {
+    for (const tag of ['include', 'hash_assign', 'parse_json']) {
+      const result = runRules({
+        check: 'DeprecatedTag',
+        params: { tag },
+        message: `Deprecated tag '${tag}'`,
+      }, {});
+      expect(result.fixes).toHaveLength(1);
+      expect(result.fixes[0].type).toBe('guidance');
+    }
+  });
+
+  test('default fallback emits no fix — no actionable next step without a known tag', () => {
+    const result = runRules({
+      check: 'DeprecatedTag',
+      params: { tag: 'foobar' },
+      message: 'irrelevant',
+    }, {});
+    expect(result.fixes).toEqual([]);
+  });
+});
diff --git a/tests/unit/rules/InvalidLayout.test.js b/tests/unit/rules/InvalidLayout.test.js
new file mode 100644
index 0000000..884329d
--- /dev/null
+++ b/tests/unit/rules/InvalidLayout.test.js
@@ -0,0 +1,183 @@
+// InvalidLayout end-to-end coverage:
+//   1. structural emitter detects the project's layout-extension convention
+//      and bakes the right `Expected file:` path into the message.
+//   2. fix-generator's `extractLayoutPath` lifts that path verbatim.
+//   3. The new `InvalidLayout.default` rule attaches a stable rule_id +
+//      create_file fix that lands at the correct path.
+//   4. `suppressUpstreamFrontmatterDup` drops the upstream
+//      `ValidFrontmatter.layout_missing` even when its line diverges from
+//      our structural emission — matched by layout NAME, not just line.
+
+import { describe, test, expect, beforeAll, beforeEach, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+import { rules as InvalidLayoutRules } from '../../../src/core/rules/InvalidLayout.js';
+import { generateStructuralWarnings } from '../../../src/core/structural-warnings.js';
+import { suppressUpstreamFrontmatterDup } from '../../../src/core/diagnostic-pipeline.js';
+import { parseLiquidFile, extractAllFromAST } from '../../../src/core/liquid-parser.js';
+
+beforeEach(() => { clearRules(); registerRules(InvalidLayoutRules); });
+
+function emit(projectDir, content, file = 'app/views/pages/x.liquid') {
+  const ast = parseLiquidFile(content);
+  const structural = extractAllFromAST(ast);
+  return generateStructuralWarnings(ast, content, file, structural, new Set(), { projectDir });
+}
+
+describe('InvalidLayout — structural emitter detects layout extension', () => {
+  let dir;
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'invalid-layout-'));
+    mkdirSync(join(dir, 'app/views/layouts'), { recursive: true });
+    // Project uses BARE .liquid (DEMO convention).
+    writeFileSync(join(dir, 'app/views/layouts/application.liquid'), '{{ content_for_layout }}');
+  });
+  afterAll(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  test('emitter picks `.liquid` extension when project uses bare suffix', () => {
+    const ws = emit(dir, '---\nlayout: nonexistent\n---\n
      x
      ');
+    const inv = ws.find(w => w.check === 'pos-supervisor:InvalidLayout');
+    expect(inv).toBeDefined();
+    expect(inv.message).toContain('app/views/layouts/nonexistent.liquid');
+    expect(inv.message).not.toContain('nonexistent.html.liquid');
+  });
+
+  test('rule lifts the corrected path into the create_file fix', () => {
+    const ws = emit(dir, '---\nlayout: nonexistent\n---\n
      x
      ');
+    const inv = ws.find(w => w.check === 'pos-supervisor:InvalidLayout');
+    const r = runRules({ check: inv.check, message: inv.message }, {});
+    expect(r.rule_id).toBe('InvalidLayout.default');
+    expect(r.fixes[0].type).toBe('create_file');
+    expect(r.fixes[0].path).toBe('app/views/layouts/nonexistent.liquid');
+    expect(r.fixes[0].path).not.toContain('html.liquid');
+  });
+});
+
+describe('InvalidLayout — emitter picks `.html.liquid` when project uses it', () => {
+  let dir;
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'invalid-layout-html-'));
+    mkdirSync(join(dir, 'app/views/layouts'), { recursive: true });
+    writeFileSync(join(dir, 'app/views/layouts/application.html.liquid'), '{{ content_for_layout }}');
+  });
+  afterAll(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  test('extension matches the existing convention', () => {
+    const ws = emit(dir, '---\nlayout: nonexistent\n---\n
      x
      ');
+    const inv = ws.find(w => w.check === 'pos-supervisor:InvalidLayout');
+    expect(inv.message).toContain('nonexistent.html.liquid');
+  });
+});
+
+describe('InvalidLayout — defaults to `.liquid` when layouts dir is empty', () => {
+  let dir;
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), 'invalid-layout-empty-'));
+    mkdirSync(join(dir, 'app/views/layouts'), { recursive: true });
+  });
+  afterAll(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  test('no existing layouts → bare suffix (modern convention)', () => {
+    const ws = emit(dir, '---\nlayout: app\n---\n
      x
      ');
+    const inv = ws.find(w => w.check === 'pos-supervisor:InvalidLayout');
+    expect(inv.message).toContain('app/views/layouts/app.liquid');
+  });
+});
+
+describe('suppressUpstreamFrontmatterDup — by layout name, line-independent', () => {
+  test('drops ValidFrontmatter `layout_missing` when InvalidLayout names same layout, even on different lines', () => {
+    const result = {
+      errors: [],
+      warnings: [
+        {
+          check: 'pos-supervisor:InvalidLayout',
+          severity: 'warning',
+          message: 'Layout `application` not found. Expected file: `app/views/layouts/application.liquid`.',
+          line: 2,
+          column: 0,
+        },
+        {
+          check: 'ValidFrontmatter',
+          severity: 'warning',
+          message: "Layout 'application' does not exist",
+          line: 99,                      // intentionally NOT 2 — would survive line-only dedup
+          column: 0,
+        },
+      ],
+      infos: [],
+    };
+    const removed = suppressUpstreamFrontmatterDup(result);
+    expect(removed).toBe(1);
+    expect(result.warnings.map(w => w.check)).toEqual(['pos-supervisor:InvalidLayout']);
+    expect(result.infos[0].message).toContain('Suppressed 1 ValidFrontmatter');
+  });
+
+  test('keeps unrelated ValidFrontmatter (different layout name)', () => {
+    const result = {
+      errors: [],
+      warnings: [
+        { check: 'pos-supervisor:InvalidLayout', message: 'Layout `application` not found. Expected file: `app/views/layouts/application.liquid`.', line: 2 },
+        { check: 'ValidFrontmatter', message: "Layout 'other_layout' does not exist", line: 5 },
+      ],
+      infos: [],
+    };
+    suppressUpstreamFrontmatterDup(result);
+    expect(result.warnings.map(w => w.check)).toEqual(['pos-supervisor:InvalidLayout', 'ValidFrontmatter']);
+  });
+
+  test('keeps non-layout ValidFrontmatter categories (deprecated_field, missing_required, etc.)', () => {
+    const result = {
+      errors: [],
+      warnings: [
+        { check: 'pos-supervisor:InvalidLayout', message: 'Layout `application` not found. Expected file: `app/views/layouts/application.liquid`.', line: 2 },
+        { check: 'ValidFrontmatter', message: 'Missing required frontmatter field `slug` in Page file', line: 1 },
+        { check: 'ValidFrontmatter', message: '`layout_name` is deprecated. Use `layout` instead.', line: 3 },
+      ],
+      infos: [],
+    };
+    suppressUpstreamFrontmatterDup(result);
+    expect(result.warnings.map(w => w.message.slice(0, 30))).toEqual([
+      'Layout `application` not found',
+      'Missing required frontmatter f',
+      '`layout_name` is deprecated. U',
+    ]);
+  });
+
+  test('still dedups on line match when layout-name match is unavailable', () => {
+    // pos-supervisor:InvalidFrontMatter (NOT InvalidLayout) — line is the
+    // only signal the dedup has for this pair.
+    const result = {
+      errors: [],
+      warnings: [
+        { check: 'pos-supervisor:InvalidFrontMatter', message: 'Unknown front-matter key', line: 4 },
+        { check: 'ValidFrontmatter', message: 'Unknown frontmatter field `weird` in Page file', line: 4 },
+      ],
+      infos: [],
+    };
+    const removed = suppressUpstreamFrontmatterDup(result);
+    expect(removed).toBe(1);
+    expect(result.warnings.map(w => w.check)).toEqual(['pos-supervisor:InvalidFrontMatter']);
+  });
+});
+
+describe('InvalidLayout rule — defensive paths', () => {
+  test('falls back to guidance when message lacks the Expected-file clause', () => {
+    const r = runRules({
+      check: 'pos-supervisor:InvalidLayout',
+      message: 'Layout `app` was not found.',          // no `Expected file:` clause
+    }, {});
+    expect(r.rule_id).toBe('InvalidLayout.default');
+    expect(r.fixes[0].type).toBe('guidance');
+  });
+
+  test('see_also points at layouts domain guide', () => {
+    const r = runRules({
+      check: 'pos-supervisor:InvalidLayout',
+      message: 'Layout `app` not found. Expected file: `app/views/layouts/app.liquid`.',
+    }, {});
+    expect(r.see_also.tool).toBe('domain_guide');
+    expect(r.see_also.args.domain).toBe('layouts');
+  });
+});
diff --git a/tests/unit/rules/MissingPartial.test.js b/tests/unit/rules/MissingPartial.test.js
index 8567fdf..aba76ac 100644
--- a/tests/unit/rules/MissingPartial.test.js
+++ b/tests/unit/rules/MissingPartial.test.js
@@ -1,6 +1,9 @@
-import { describe, test, expect, beforeEach } from 'bun:test';
+import { describe, test, expect, beforeEach, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
-import { rules } from '../../../src/core/rules/MissingPartial.js';
+import { rules, parseModulePath } from '../../../src/core/rules/MissingPartial.js';
 import { buildFactGraph } from '../../../src/core/project-fact-graph.js';
 
 const FIXTURE_MAP = {
@@ -36,7 +39,7 @@ describe('MissingPartial.module_path', () => {
     expect(result.rule_id).toBe('MissingPartial.module_path');
     expect(result.see_also.tool).toBe('module_info');
     expect(result.see_also.args.name).toBe('user');
-    expect(result.confidence).toBe(0.9);
+    expect(result.confidence).toBeGreaterThanOrEqual(0.7);
   });
 
   test('does not fire for project partials', () => {
@@ -46,6 +49,111 @@ describe('MissingPartial.module_path', () => {
   });
 });
 
+describe('MissingPartial.module_path — projectDir-aware behavior', () => {
+  let projectDir;
+
+  beforeAll(() => {
+    projectDir = mkdtempSync(join(tmpdir(), 'mp-modpath-'));
+
+    const writeFile = (rel) => {
+      const abs = join(projectDir, rel);
+      mkdirSync(join(abs, '..'), { recursive: true });
+      writeFileSync(abs, '');
+    };
+
+    // core: only `execute` is exported as a command, plus a deeper helper tree
+    writeFile('modules/core/public/lib/commands/execute.liquid');
+    writeFile('modules/core/public/lib/commands/email/send/build.liquid');
+    writeFile('modules/core/public/lib/commands/email/send/check.liquid');
+    writeFile('modules/core/public/lib/queries/users/find.liquid');
+    writeFile('modules/core/public/lib/helpers/auth_token.liquid');
+
+    // user: only helpers
+    writeFile('modules/user/public/lib/helpers/current.liquid');
+  });
+
+  afterAll(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test('build/check special case: explains they are inline phases of caller command', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/core/commands/build' } };
+    const result = runRules(diag, { ...facts, projectDir });
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+    expect(result.hint_md).toContain('inline phases of your own command');
+    expect(result.hint_md).toContain('modules/core/commands/execute');
+    // closest matches block must enumerate live exports
+    expect(result.hint_md).toContain('modules/core/commands/execute');
+    // exported categories summary
+    expect(result.hint_md).toContain('Exported categories:');
+    expect(result.hint_md).toMatch(/commands \(\d+\)/);
+  });
+
+  test('build/check special case fires for `check` symmetrically', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/core/commands/check' } };
+    const result = runRules(diag, { ...facts, projectDir });
+    expect(result.hint_md).toContain('inline phases of your own command');
+    expect(result.fixes[0].description).toContain('inline the build/check logic');
+  });
+
+  test('non-existing path inside an installed module: lists Levenshtein candidates', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/core/queries/users/fnd' } };
+    const result = runRules(diag, { ...facts, projectDir });
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+    expect(result.hint_md).toContain('not exported by module `core`');
+    expect(result.hint_md).toContain('modules/core/queries/users/find');
+    expect(result.fixes[0].description).toContain('modules/core/queries/users/find');
+    expect(result.confidence).toBe(0.9);
+  });
+
+  test('module not installed: suggests the closest installed module', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/cre/commands/execute' } };
+    const result = runRules(diag, { ...facts, projectDir });
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+    expect(result.hint_md).toContain('Module `cre` is not installed');
+    expect(result.hint_md).toContain('Installed modules:');
+    expect(result.hint_md).toContain('Did you mean `core`');
+    expect(result.see_also.tool).toBe('project_map');
+  });
+
+  test('module not installed and no modules dir: still produces a hint', () => {
+    const isolatedDir = mkdtempSync(join(tmpdir(), 'mp-empty-'));
+    try {
+      const diag = { check: 'MissingPartial', params: { partial: 'modules/anything/commands/execute' } };
+      const result = runRules(diag, { ...facts, projectDir: isolatedDir });
+      expect(result.rule_id).toBe('MissingPartial.module_path');
+      expect(result.hint_md).toContain('Module `anything` is not installed');
+      expect(result.hint_md).toContain('No modules are installed');
+    } finally {
+      rmSync(isolatedDir, { recursive: true, force: true });
+    }
+  });
+
+  test('no projectDir in facts: rule still fires with degraded hint (no exports)', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/core/commands/build' } };
+    const result = runRules(diag, facts); // no projectDir
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+    expect(result.hint_md).toContain('inline phases of your own command');
+    // no live exports → no closest matches
+    expect(result.hint_md).toContain('(no close matches in this module)');
+  });
+
+  test('parseModulePath: splits into moduleName / category / rest', () => {
+    expect(parseModulePath('modules/core/commands/email/send/build'))
+      .toEqual({ moduleName: 'core', category: 'commands', rest: 'email/send/build' });
+    expect(parseModulePath('modules/core/commands/build'))
+      .toEqual({ moduleName: 'core', category: 'commands', rest: 'build' });
+    expect(parseModulePath('modules/core/commands'))
+      .toEqual({ moduleName: 'core', category: 'commands', rest: null });
+    expect(parseModulePath('modules/core'))
+      .toEqual({ moduleName: 'core', category: null, rest: null });
+    expect(parseModulePath(''))
+      .toEqual({ moduleName: null, category: null, rest: null });
+    expect(parseModulePath('app/lib/commands/foo'))
+      .toEqual({ moduleName: null, category: null, rest: null });
+  });
+});
+
 describe('MissingPartial.file_exists', () => {
   test('fires when target file exists in graph', () => {
     const diag = { check: 'MissingPartial', params: { partial: 'blog_posts/card' } };
diff --git a/tests/unit/rules/NonGetRenderingPage.test.js b/tests/unit/rules/NonGetRenderingPage.test.js
new file mode 100644
index 0000000..c89f0a0
--- /dev/null
+++ b/tests/unit/rules/NonGetRenderingPage.test.js
@@ -0,0 +1,187 @@
+// NonGetRenderingPage three-subrule routing — covers each path through
+// `validatePageMethodAndForms` (structural-warnings.js) end-to-end into the
+// rule engine. Test cases mirror the gist analysis at
+// docs/rule-performance-plan.md / NonGetRenderingPageRule.md.
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+import { rules } from '../../../src/core/rules/NonGetRenderingPage.js';
+import { generateStructuralWarnings } from '../../../src/core/structural-warnings.js';
+import { parseLiquidFile, extractAllFromAST } from '../../../src/core/liquid-parser.js';
+
+beforeEach(() => { clearRules(); registerRules(rules); });
+
+function emit(file, content) {
+  const ast = parseLiquidFile(content);
+  const structural = extractAllFromAST(ast);
+  const ws = generateStructuralWarnings(ast, content, file, structural, new Set(), {});
+  return ws.filter(w => w.check === 'pos-supervisor:NonGetRenderingPage');
+}
+
+function route(diag) {
+  return runRules({ ...diag }, {});
+}
+
+describe('NonGetRenderingPage.html_on_post', () => {
+  test('non-API POST page with layout fires html_on_post', () => {
+    const ws = emit('app/views/pages/contact.liquid',
+      '---\nslug: contact\nmethod: post\nlayout: application\n---\n
      Contact
      ');
+    expect(ws).toHaveLength(1);
+    const r = route(ws[0]);
+    expect(r.rule_id).toBe('NonGetRenderingPage.html_on_post');
+    expect(r.fixes[0].description).toContain('landing page');
+    expect(r.fixes[0].description).toContain('API handler');
+  });
+
+  test('hint references both UI-page and API-handler shapes', () => {
+    const ws = emit('app/views/pages/contact.liquid',
+      '---\nslug: contact\nmethod: post\nlayout: application\n---\n
      x
      ');
+    const r = route(ws[0]);
+    expect(r.hint_md).toContain('Landing / display page');
+    expect(r.hint_md).toContain('Form-handling endpoint');
+    expect(r.hint_md).toContain("action=\"/api/contacts/create\"");
+  });
+
+  test('non-API PUT/DELETE/PATCH pages with HTML also fire', () => {
+    for (const method of ['put', 'delete', 'patch']) {
+      const ws = emit('app/views/pages/x.liquid',
+        `---\nslug: x\nmethod: ${method}\nlayout: application\n---\n
      x
      `);
+      expect(ws).toHaveLength(1);
+      const r = route(ws[0]);
+      expect(r.rule_id).toBe('NonGetRenderingPage.html_on_post');
+      expect(r.hint_md).toContain(`method: ${method}`);
+    }
+  });
+
+  test('POST page with no HTML (redirect-only handler) does NOT fire', () => {
+    const ws = emit('app/views/pages/contacts.liquid',
+      '---\nslug: contacts\nmethod: post\n---\n{% graphql r = "contacts/create" %}');
+    expect(ws).toEqual([]);
+  });
+});
+
+describe('NonGetRenderingPage.api_renders_html', () => {
+  test('API page with layout fires api_renders_html', () => {
+    const ws = emit('app/views/pages/api/contacts/create.liquid',
+      '---\nslug: api/contacts/create\nmethod: post\nlayout: application\n---\n
      Creating
      ');
+    expect(ws).toHaveLength(1);
+    const r = route(ws[0]);
+    expect(r.rule_id).toBe('NonGetRenderingPage.api_renders_html');
+    expect(r.hint_md).toContain('format: json');
+    expect(r.hint_md).toContain('result | json');
+  });
+
+  test('API page missing format:json fires even without HTML body', () => {
+    const ws = emit('app/views/pages/api/contacts/create.liquid',
+      '---\nslug: api/contacts/create\nmethod: post\n---\n{% graphql r = "contacts/create" %}\n{{ r | json }}');
+    expect(ws).toHaveLength(1);
+    const r = route(ws[0]);
+    expect(r.rule_id).toBe('NonGetRenderingPage.api_renders_html');
+    expect(r.hint_md).toContain('format: json');
+  });
+
+  test('valid API endpoint with format:json + json body emits NOTHING', () => {
+    const ws = emit('app/views/pages/api/contacts/create.liquid',
+      '---\nslug: api/contacts/create\nmethod: post\nformat: json\n---\n{% graphql r = "contacts/create" %}\n{{ r | json }}');
+    expect(ws).toEqual([]);
+  });
+
+  test('/_/ and /internal/ prefixes are also API paths', () => {
+    for (const prefix of ['_', 'internal']) {
+      const ws = emit(`app/views/pages/${prefix}/x.liquid`,
+        `---\nslug: ${prefix}/x\nmethod: post\nlayout: application\n---\n
      x
      `);
+      expect(ws).toHaveLength(1);
+      const r = route(ws[0]);
+      expect(r.rule_id).toBe('NonGetRenderingPage.api_renders_html');
+    }
+  });
+
+  test('extracted slug appears in hint canonical-shape example', () => {
+    const ws = emit('app/views/pages/api/foo/bar.liquid',
+      '---\nslug: api/foo/bar\nmethod: put\nlayout: application\n---\n
      x
      ');
+    const r = route(ws[0]);
+    expect(r.hint_md).toContain('slug: api/foo/bar');
+    expect(r.hint_md).toContain('method: put');
+  });
+});
+
+describe('NonGetRenderingPage.get_form_target', () => {
+  test('GET page with form to non-API path fires get_form_target', () => {
+    const ws = emit('app/views/pages/index.liquid',
+      '---\nslug: index\n---\n
      ');
+    expect(ws).toHaveLength(1);
+    const r = route(ws[0]);
+    expect(r.rule_id).toBe('NonGetRenderingPage.get_form_target');
+    expect(r.hint_md).toContain('/api/contacts/create');
+    expect(r.hint_md).toContain('app/views/pages/api/contacts/create.liquid');
+  });
+
+  test('form action under /api/ is sanctioned — no diagnostic', () => {
+    const ws = emit('app/views/pages/index.liquid',
+      '---\nslug: index\n---\n
      ');
+    expect(ws).toEqual([]);
+  });
+
+  test('self-posting form (action == own slug) is sanctioned — no diagnostic', () => {
+    const ws = emit('app/views/pages/contacts.liquid',
+      '---\nslug: contacts\n---\n
      ');
+    expect(ws).toEqual([]);
+  });
+
+  test('GET form (method="get") is not flagged — no submission risk', () => {
+    const ws = emit('app/views/pages/search.liquid',
+      '---\nslug: search\n---\n
      ');
+    expect(ws).toEqual([]);
+  });
+
+  test('attribute order is irrelevant — action before method works', () => {
+    const ws = emit('app/views/pages/index.liquid',
+      '---\nslug: index\n---\n
      ');
+    expect(ws).toHaveLength(1);
+    expect(route(ws[0]).rule_id).toBe('NonGetRenderingPage.get_form_target');
+  });
+
+  test('multiple forms — emits one diagnostic per offending form', () => {
+    const ws = emit('app/views/pages/index.liquid',
+      '---\nslug: index\n---\n
      \n
      \n
      ');
+    expect(ws).toHaveLength(2);
+    const actions = ws.map(w => w.message.match(/posts to `([^`]+)`/)?.[1]);
+    expect(actions).toEqual(['/a', '/c']);
+  });
+
+  test('form with single quotes parses correctly', () => {
+    const ws = emit('app/views/pages/index.liquid',
+      "---\nslug: index\n---\n
      ");
+    expect(ws).toHaveLength(1);
+    expect(route(ws[0]).rule_id).toBe('NonGetRenderingPage.get_form_target');
+  });
+});
+
+describe('NonGetRenderingPage default fallback', () => {
+  test('unknown subtype message routes to default rule', () => {
+    const r = runRules({
+      check: 'pos-supervisor:NonGetRenderingPage',
+      message: 'Some new diagnostic shape we have not seen',
+    }, {});
+    expect(r.rule_id).toBe('NonGetRenderingPage.default');
+    expect(r.confidence).toBeLessThanOrEqual(0.6);
+  });
+});
+
+describe('NonGetRenderingPage — DEMO regression cases', () => {
+  test('the original DEMO failure (POST landing page) now ships actionable fix', () => {
+    // Pre-task-4 the rule was `NonGetRenderingPage.default` with `fixes: []`
+    // and 25 outcomes (5 resolved / 15 unchanged / 5 regressed).
+    const ws = emit('app/views/pages/contact.liquid',
+      '---\nslug: contact\nmethod: post\nlayout: application\n---\n
      Contact
      \n
      ...
      ');
+    expect(ws).toHaveLength(1);
+    const r = route(ws[0]);
+    expect(r.rule_id).toBe('NonGetRenderingPage.html_on_post');
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes[0].type).toBe('guidance');
+    // Hint disambiguates the two valid intents (landing vs API handler) so
+    // the agent's loop-on-unchanged behaviour stops.
+    expect(r.hint_md).toContain('Landing / display page');
+    expect(r.hint_md).toContain('Form-handling endpoint');
+  });
+});
diff --git a/tests/unit/rules/Tier1Rules.test.js b/tests/unit/rules/Tier1Rules.test.js
index e4be094..2f264a6 100644
--- a/tests/unit/rules/Tier1Rules.test.js
+++ b/tests/unit/rules/Tier1Rules.test.js
@@ -62,18 +62,27 @@ describe('ConvertIncludeToRender.default', () => {
   });
 });
 
-describe('NonGetRenderingPage.default', () => {
+describe('NonGetRenderingPage.default — fallback for non-discriminated messages', () => {
   beforeEach(() => { clearRules(); registerRules(NonGetRenderingPageRules); });
 
-  test('fires with canonical rule_id + action-oriented hint', () => {
+  // After the task-4 split into three subrules (html_on_post / api_renders_html
+  // / get_form_target) the default rule only fires when none of the
+  // discriminator regexes match. Subrule routing is exercised in
+  // tests/unit/rules/NonGetRenderingPage.test.js — this case is the
+  // safety net for upstream message-shape drift.
+  test('fires with canonical rule_id + names the three valid platformOS shapes', () => {
     const result = runRules(
-      { check: 'pos-supervisor:NonGetRenderingPage', message: 'page method: post + renders HTML' },
+      { check: 'pos-supervisor:NonGetRenderingPage', message: 'a brand-new diagnostic shape this rule has not seen before' },
       { graph: null },
     );
     expect(result.rule_id).toBe('NonGetRenderingPage.default');
-    expect(result.confidence).toBe(0.9);
-    expect(result.hint_md).toMatch(/method: post/i);
-    expect(result.hint_md).toMatch(/api/i);
-    expect(result.fixes).toEqual([]);
+    expect(result.confidence).toBeLessThanOrEqual(0.6);   // fallback confidence is intentionally lower
+    expect(result.hint_md).toMatch(/UI page/);
+    expect(result.hint_md).toMatch(/API endpoint/);
+    expect(result.hint_md).toMatch(/Forms on GET pages/);
+    // The fallback now ships a single guidance fix (the old empty-fixes
+    // behaviour drove the DEMO loop-on-unchanged regression).
+    expect(result.fixes).toHaveLength(1);
+    expect(result.fixes[0].type).toBe('guidance');
   });
 });
diff --git a/tests/unit/rules/Tier3Rules.test.js b/tests/unit/rules/Tier3Rules.test.js
new file mode 100644
index 0000000..679733f
--- /dev/null
+++ b/tests/unit/rules/Tier3Rules.test.js
@@ -0,0 +1,185 @@
+// Tier 3 promotion tests — every Bucket B `.unmatched` check that gained a
+// rule module in task 3 phase 1. Scope: stable rule_id, structured hint,
+// guidance fix that doesn't compete with the existing fix-generator
+// heuristic (where one exists). Each describe block targets one check.
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+
+import { rules as UnrecognizedRules } from '../../../src/core/rules/UnrecognizedRenderPartialArguments.js';
+import { rules as SchemaPropertyRules } from '../../../src/core/rules/SchemaProperty.js';
+import { rules as SchemaYAMLRules } from '../../../src/core/rules/SchemaYAML.js';
+import { rules as MissingSlugRules } from '../../../src/core/rules/MissingSlug.js';
+import { rules as MissingContentRules } from '../../../src/core/rules/MissingContentForLayout.js';
+import { rules as ParserBlockingRules } from '../../../src/core/rules/ParserBlockingScript.js';
+import { rules as TranslationLocaleRules } from '../../../src/core/rules/TranslationMissingLocaleKey.js';
+
+describe('UnrecognizedRenderPartialArguments rule', () => {
+  beforeEach(() => { clearRules(); registerRules(UnrecognizedRules); });
+
+  test('extracts argument + partial from message and renders concrete options', () => {
+    const r = runRules({
+      check: 'UnrecognizedRenderPartialArguments',
+      params: {},
+      message: "Unknown argument 'extra' in render tag for partial 'shared/card'.",
+    }, {});
+    expect(r.rule_id).toBe('UnrecognizedRenderPartialArguments.default');
+    expect(r.hint_md).toContain('`extra`');
+    expect(r.hint_md).toContain('`shared/card`');
+    expect(r.hint_md).toContain('`@param`');
+    // For project partials, all three options (drop / declare / rename) are valid.
+    expect(r.hint_md).toContain('Add a matching `@param`');
+  });
+
+  test('module partials disable the "add @param" option', () => {
+    const r = runRules({
+      check: 'UnrecognizedRenderPartialArguments',
+      params: {},
+      message: "Unknown argument 'params' in render tag for partial 'modules/common-styling/toasts'.",
+    }, {});
+    expect(r.hint_md).toContain('module partials are read-only');
+    expect(r.fixes[0].description).toContain('Module partials are read-only');
+  });
+
+  test('falls back gracefully when the message can\'t be parsed', () => {
+    const r = runRules({
+      check: 'UnrecognizedRenderPartialArguments',
+      params: {},
+      message: 'unparseable nonsense',
+    }, {});
+    expect(r.rule_id).toBe('UnrecognizedRenderPartialArguments.default');
+    expect(r.hint_md).toContain('the unrecognized argument');
+    expect(r.hint_md).toContain('the target partial');
+  });
+});
+
+describe('SchemaProperty rule', () => {
+  beforeEach(() => { clearRules(); registerRules(SchemaPropertyRules); });
+
+  const cases = [
+    { msg: 'Property name `created_at` conflicts with built-in field. Built-in fields (id, created_at, updated_at, table) are added automatically.', sub: 'builtin_conflict' },
+    { msg: 'Duplicate property name `email`. Property names must be unique within a schema.', sub: 'duplicate_name' },
+    { msg: 'Property name `2nd_field` must start with a letter, not a digit.', sub: 'invalid_identifier' },
+    { msg: 'Property name `myField` should use snake_case (lowercase letters, numbers, underscores).', sub: 'snake_case' },
+    { msg: 'Property `avatar`: Unknown upload option `cdn`. Valid options: acl, max_size, content_type.', sub: 'upload_options' },
+    { msg: 'properties[2]: Missing required `name` key.', sub: 'missing_field' },
+    { msg: 'Property `email`: `required` is not a schema-level concept in platformOS. Validation must be done in mutations/commands.', sub: 'misleading_key' },
+    { msg: 'Property `email`: some unfamiliar message', sub: 'default' },
+  ];
+
+  for (const { msg, sub } of cases) {
+    test(`routes "${msg.slice(0, 40)}..." → SchemaProperty.${sub}`, () => {
+      const r = runRules({ check: 'pos-supervisor:SchemaProperty', params: {}, message: msg }, {});
+      expect(r.rule_id).toBe(`SchemaProperty.${sub}`);
+      expect(r.fixes).toHaveLength(1);
+      expect(r.fixes[0].type).toBe('guidance');
+      expect(r.see_also.tool).toBe('domain_guide');
+      expect(r.see_also.args.domain).toBe('schema');
+    });
+  }
+});
+
+describe('SchemaYAML rule', () => {
+  beforeEach(() => { clearRules(); registerRules(SchemaYAMLRules); });
+
+  test('attaches stable rule_id + hint with common YAML pitfalls', () => {
+    const r = runRules({
+      check: 'pos-supervisor:SchemaYAML',
+      params: {},
+      message: 'Invalid YAML syntax: expected a single document in the stream',
+    }, {});
+    expect(r.rule_id).toBe('SchemaYAML.default');
+    expect(r.hint_md).toContain('Single document only');
+    expect(r.hint_md).toContain('Indentation mismatch');
+    expect(r.see_also.args.domain).toBe('schema');
+  });
+});
+
+describe('MissingSlug rule', () => {
+  beforeEach(() => { clearRules(); registerRules(MissingSlugRules); });
+
+  test('promotes to stable rule_id and emits guidance only (heuristic owns text_edit)', () => {
+    const r = runRules({
+      check: 'pos-supervisor:MissingSlug',
+      params: {},
+      message: 'Page is missing `slug` in front matter.',
+    }, {});
+    expect(r.rule_id).toBe('MissingSlug.default');
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes[0].type).toBe('guidance');
+    expect(r.hint_md).toContain('kebab-case');
+    expect(r.hint_md).toContain(':param');
+    expect(r.see_also.args.domain).toBe('pages');
+  });
+});
+
+describe('MissingContentForLayout rule', () => {
+  beforeEach(() => { clearRules(); registerRules(MissingContentRules); });
+
+  test('promotes to stable rule_id and explains content_for_layout vs yield', () => {
+    const r = runRules({
+      check: 'pos-supervisor:MissingContentForLayout',
+      params: {},
+      message: 'Layout is missing `{{ content_for_layout }}`.',
+    }, {});
+    expect(r.rule_id).toBe('MissingContentForLayout.default');
+    expect(r.hint_md).toContain('`{{ content_for_layout }}`');
+    expect(r.hint_md).toContain('{% yield');
+    expect(r.fixes[0].type).toBe('guidance');
+    expect(r.see_also.args.domain).toBe('layouts');
+  });
+});
+
+describe('ParserBlockingScript rule', () => {
+  beforeEach(() => { clearRules(); registerRules(ParserBlockingRules); });
+
+  test('emits decision tree (defer / async / end-of-body)', () => {
+    const r = runRules({
+      check: 'ParserBlockingScript',
+      params: {},
+      message: 'Avoid parser blocking scripts by adding `defer` or `async`',
+    }, {});
+    expect(r.rule_id).toBe('ParserBlockingScript.default');
+    expect(r.hint_md).toContain('defer');
+    expect(r.hint_md).toContain('async');
+    expect(r.fixes[0].description).toContain('defer');
+  });
+});
+
+describe('TranslationMissingLocaleKey rule', () => {
+  beforeEach(() => { clearRules(); registerRules(TranslationLocaleRules); });
+
+  test('extracts locale from message and emits before/after YAML example', () => {
+    const r = runRules({
+      check: 'pos-supervisor:TranslationMissingLocaleKey',
+      params: {},
+      message: "Translation file has no top-level locale key. Top-level keys found: app. Wrap the entire tree in the file's locale (e.g. `en:`) — platformOS indexes translations by locale at the root.",
+    }, {});
+    expect(r.rule_id).toBe('TranslationMissingLocaleKey.default');
+    expect(r.hint_md).toMatch(/Wrap the entire tree under `en:`/);
+    expect(r.hint_md).toContain('# BEFORE');
+    expect(r.hint_md).toContain('# AFTER');
+    // Extracted locale appears in the generated example.
+    expect(r.hint_md).toMatch(/^en:/m);
+    expect(r.see_also.args.domain).toBe('translations');
+  });
+
+  test('handles non-en locales (de, pt-BR)', () => {
+    const r = runRules({
+      check: 'pos-supervisor:TranslationMissingLocaleKey',
+      params: {},
+      message: "Translation file has no top-level locale key. Top-level keys found: app. Wrap the entire tree in the file's locale (e.g. `pt-BR:`) — platformOS indexes translations by locale at the root.",
+    }, {});
+    expect(r.hint_md).toMatch(/Wrap the entire tree under `pt-BR:`/);
+    expect(r.hint_md).toMatch(/^pt-BR:/m);
+  });
+
+  test('falls back to `en` when locale hint missing from message', () => {
+    const r = runRules({
+      check: 'pos-supervisor:TranslationMissingLocaleKey',
+      params: {},
+      message: 'Translation file has no top-level locale key.',
+    }, {});
+    expect(r.hint_md).toMatch(/Wrap the entire tree under `en:`/);
+  });
+});
diff --git a/tests/unit/rules/Tier3RulesPhase2.test.js b/tests/unit/rules/Tier3RulesPhase2.test.js
new file mode 100644
index 0000000..b44f80f
--- /dev/null
+++ b/tests/unit/rules/Tier3RulesPhase2.test.js
@@ -0,0 +1,204 @@
+// Tier 3 phase 2 — Levenshtein + structural rule modules:
+// MissingAsset, OrphanedPartial, MissingPage, LiquidHTMLSyntaxError.
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+import { buildFactGraph } from '../../../src/core/project-fact-graph.js';
+
+import { rules as MissingAssetRules } from '../../../src/core/rules/MissingAsset.js';
+import { rules as OrphanedPartialRules } from '../../../src/core/rules/OrphanedPartial.js';
+import { rules as MissingPageRules } from '../../../src/core/rules/MissingPage.js';
+import { rules as LiquidHTMLSyntaxErrorRules } from '../../../src/core/rules/LiquidHTMLSyntaxError.js';
+
+describe('MissingAsset rule', () => {
+  const graph = buildFactGraph({
+    pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {},
+    assets: ['images/logo.png', 'styles/main.css', 'styles/main.scss', 'scripts/app.js'],
+  });
+  const facts = { graph };
+
+  beforeEach(() => { clearRules(); registerRules(MissingAssetRules); });
+
+  test('subdir_prefix: bare filename matching a known-subdir asset → fix the reference', () => {
+    const r = runRules({ check: 'MissingAsset', message: "'logo.png' does not exist" }, facts);
+    expect(r.rule_id).toBe('MissingAsset.missing_subdir_prefix');
+    expect(r.hint_md).toContain('images/logo.png');
+    expect(r.fixes[0].description).toContain('images/logo.png');
+    expect(r.confidence).toBeGreaterThanOrEqual(0.85);
+  });
+
+  test('suggest_nearest: typo in subdir asset → Levenshtein candidates', () => {
+    const r = runRules({ check: 'MissingAsset', message: "'styles/maain.css' does not exist" }, facts);
+    expect(r.rule_id).toBe('MissingAsset.suggest_nearest');
+    expect(r.hint_md).toContain('styles/main.css');
+  });
+
+  test('create_file: no near match → propose creation, lower confidence', () => {
+    const r = runRules({ check: 'MissingAsset', message: "'foo/bar.css' does not exist" }, facts);
+    expect(r.rule_id).toBe('MissingAsset.create_file');
+    expect(r.confidence).toBeLessThanOrEqual(0.7);
+  });
+
+  test('subdir_prefix only fires for known asset subdirs (avoids false matches)', () => {
+    const stranger = buildFactGraph({
+      pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {},
+      assets: ['vendor/data/logo.png'],   // NOT under known subdir
+    });
+    clearRules(); registerRules(MissingAssetRules);
+    const r = runRules({ check: 'MissingAsset', message: "'logo.png' does not exist" }, { graph: stranger });
+    // Should NOT match subdir_prefix — `vendor` is not in KNOWN_ASSET_SUBDIRS.
+    // Falls through to suggest_nearest (or create_file if no Levenshtein match).
+    expect(r.rule_id).not.toBe('MissingAsset.missing_subdir_prefix');
+  });
+});
+
+describe('OrphanedPartial rule', () => {
+  beforeEach(() => { clearRules(); registerRules(OrphanedPartialRules); });
+
+  test('partial with zero callers → propose delete_file + guidance', () => {
+    const graph = buildFactGraph({
+      pages: {}, partials: {
+        'foo/orphan': { path: 'app/views/partials/foo/orphan.liquid', params: [], renders: [], render_calls: [], function_calls: [], rendered_by: [] },
+      }, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [],
+    });
+    const r = runRules({
+      check: 'OrphanedPartial',
+      file: 'app/views/partials/foo/orphan.liquid',
+      message: 'This partial is not referenced by any other files',
+    }, { graph });
+    expect(r.rule_id).toBe('OrphanedPartial.default');
+    expect(r.fixes.some(f => f.type === 'delete_file')).toBe(true);
+    expect(r.fixes.some(f => f.type === 'guidance')).toBe(true);
+    expect(r.hint_md).toContain('Work in progress');
+    expect(r.hint_md).toContain('pending_files');
+  });
+
+  test('layout with no callers → softer guidance, no delete_file', () => {
+    const graph = buildFactGraph({
+      pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {},
+      layouts: {
+        'app/views/layouts/unused.liquid': { path: 'app/views/layouts/unused.liquid', renders: [], render_calls: [], function_calls: [] },
+      },
+      translations: {}, assets: [],
+    });
+    const r = runRules({
+      check: 'OrphanedPartial',
+      file: 'app/views/layouts/unused.liquid',
+      message: 'This partial is not referenced by any other files',
+    }, { graph });
+    expect(r.rule_id).toBe('OrphanedPartial.default');
+    expect(r.fixes.some(f => f.type === 'delete_file')).toBe(false);
+    expect(r.hint_md).toContain('layout');
+  });
+
+  test('falls back gracefully without diag.file', () => {
+    const r = runRules({
+      check: 'OrphanedPartial',
+      message: 'This partial is not referenced by any other files',
+    }, { graph: buildFactGraph({ pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [] }) });
+    expect(r.rule_id).toBe('OrphanedPartial.default');
+    // Without a path, no delete_file proposal — too dangerous.
+    expect(r.fixes.some(f => f.type === 'delete_file')).toBe(false);
+  });
+});
+
+describe('MissingPage rule', () => {
+  const graph = buildFactGraph({
+    pages: {
+      'idx': { path: 'app/views/pages/index.liquid', slug: '', method: 'get', renders: [] },
+      'notes:get': { path: 'app/views/pages/notes/index.html.liquid', slug: 'notes', method: 'get', renders: [] },
+      'dashboard:get': { path: 'app/views/pages/dashboard.liquid', slug: 'dashboard', method: 'get', renders: [] },
+    },
+    partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [],
+  });
+
+  beforeEach(() => { clearRules(); registerRules(MissingPageRules); });
+
+  test('typo: close to existing slug → suggest rename', () => {
+    const r = runRules({
+      check: 'MissingPage',
+      message: "No page found for route '/noets' (GET)",
+    }, { graph });
+    expect(r.rule_id).toBe('MissingPage.typo');
+    expect(r.hint_md).toContain('/notes');
+  });
+
+  test('default: no near match → three-option decision tree + create_file', () => {
+    const r = runRules({
+      check: 'MissingPage',
+      message: "No page found for route '/profile' (GET)",
+    }, { graph });
+    expect(r.rule_id).toBe('MissingPage.default');
+    expect(r.hint_md).toContain('Typo in the reference');
+    expect(r.hint_md).toContain('New page');
+    expect(r.hint_md).toContain('Method mismatch');
+    expect(r.fixes[0].type).toBe('create_file');
+    expect(r.fixes[0].path).toBe('app/views/pages/profile.liquid');
+  });
+
+  test('root route → suggests omitting slug, points at index.liquid', () => {
+    const r = runRules({
+      check: 'MissingPage',
+      message: "No page found for route '/' (GET)",
+    }, { graph: buildFactGraph({ pages:{}, partials:{}, commands:{}, queries:{}, graphql:{}, schema:{}, layouts:{}, translations:{}, assets:[] }) });
+    expect(r.rule_id).toBe('MissingPage.default');
+    expect(r.fixes[0].path).toBe('app/views/pages/index.liquid');
+    expect(r.hint_md).toContain('omit `slug:`');
+  });
+
+  test('extracts method from message', () => {
+    const r = runRules({
+      check: 'MissingPage',
+      message: "No page found for route '/api/sync' (POST)",
+    }, { graph });
+    expect(r.hint_md).toContain('(POST)');
+  });
+});
+
+describe('LiquidHTMLSyntaxError rule', () => {
+  beforeEach(() => { clearRules(); registerRules(LiquidHTMLSyntaxErrorRules); });
+
+  test('unknown_tag fires on "Unknown tag" message + suggests via tagsIndex', () => {
+    const tagsIndex = {
+      platformOSTags: () => [
+        { name: 'assign' }, { name: 'render' }, { name: 'function' }, { name: 'graphql' }, { name: 'if' }, { name: 'for' },
+      ],
+    };
+    const r = runRules({
+      check: 'LiquidHTMLSyntaxError',
+      message: "Unknown tag 'assigns'",
+    }, { tagsIndex });
+    expect(r.rule_id).toBe('LiquidHTMLSyntaxError.unknown_tag');
+    expect(r.hint_md).toContain('assign');
+  });
+
+  test('unknown_tag works without tagsIndex (no suggestion, still attributes)', () => {
+    const r = runRules({
+      check: 'LiquidHTMLSyntaxError',
+      message: "Unknown tag 'foo'",
+    }, {});
+    expect(r.rule_id).toBe('LiquidHTMLSyntaxError.unknown_tag');
+    expect(r.hint_md).toContain('foo');
+  });
+
+  test('for_loop_args fires when filter pipeline appears in for loop header', () => {
+    const r = runRules({
+      check: 'LiquidHTMLSyntaxError',
+      message: "Arguments must be provided in the format `for in   `. Invalid/Unknown arguments: |, t",
+    }, {});
+    expect(r.rule_id).toBe('LiquidHTMLSyntaxError.for_loop_args');
+    expect(r.hint_md).toContain('assign items');
+    // The fix description cross-references the translation-array sibling rule
+    // (the most common origin of `| t` inside a for header).
+    expect(r.fixes[0].description).toContain('TranslationKeyExists.array_index_misuse');
+  });
+
+  test('default fallback for unknown shapes', () => {
+    const r = runRules({
+      check: 'LiquidHTMLSyntaxError',
+      message: 'something obscure happened',
+    }, {});
+    expect(r.rule_id).toBe('LiquidHTMLSyntaxError.default');
+    expect(r.confidence).toBeLessThanOrEqual(0.6);
+  });
+});
diff --git a/tests/unit/rules/Tier3RulesPhase3.test.js b/tests/unit/rules/Tier3RulesPhase3.test.js
new file mode 100644
index 0000000..ab242f5
--- /dev/null
+++ b/tests/unit/rules/Tier3RulesPhase3.test.js
@@ -0,0 +1,358 @@
+// Tier-3 phase 3 — high-volume bucket-B promotions:
+//   • PartialCallArguments (28 emits in DEMO; 4 subrules)
+//   • GraphQLVariablesCheck (3 emits; signature block via graph)
+//   • UnusedDocParam       (11 emits; caller-aware confidence)
+//
+// Also covers the diagnostic-record extractors that feed these rules.
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { clearRules, registerRules, runRules } from '../../../src/core/rules/engine.js';
+import { extractParams } from '../../../src/core/diagnostic-record.js';
+import { buildFactGraph } from '../../../src/core/project-fact-graph.js';
+
+import { rules as PartialCallArgumentsRules } from '../../../src/core/rules/PartialCallArguments.js';
+import { rules as GraphQLVariablesCheckRules } from '../../../src/core/rules/GraphQLVariablesCheck.js';
+import { rules as UnusedDocParamRules } from '../../../src/core/rules/UnusedDocParam.js';
+
+describe('extractParams — PartialCallArguments / GraphQLVariablesCheck / UnusedDocParam', () => {
+  test('PartialCallArguments — required, function call', () => {
+    expect(extractParams('PartialCallArguments', 'Required parameter key must be passed to function call'))
+      .toEqual({ param_name: 'key', direction: 'required', call_kind: 'function', is_function_call: 'true' });
+  });
+  test('PartialCallArguments — required, render call', () => {
+    expect(extractParams('PartialCallArguments', 'Required parameter success must be passed to render call'))
+      .toEqual({ param_name: 'success', direction: 'required', call_kind: 'render', is_function_call: 'false' });
+  });
+  test('PartialCallArguments — unknown, render call', () => {
+    expect(extractParams('PartialCallArguments', 'Unknown parameter params passed to render call'))
+      .toEqual({ param_name: 'params', direction: 'unknown', call_kind: 'render', is_function_call: 'false' });
+  });
+  test('PartialCallArguments — extractor returns {} on unknown shape', () => {
+    expect(extractParams('PartialCallArguments', 'something brand new')).toEqual({});
+  });
+  test('GraphQLVariablesCheck — required', () => {
+    expect(extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'))
+      .toEqual({ param_name: 'name', direction: 'required', call_kind: 'graphql' });
+  });
+  test('GraphQLVariablesCheck — unknown', () => {
+    expect(extractParams('GraphQLVariablesCheck', 'Unknown parameter foo passed to GraphQL call'))
+      .toEqual({ param_name: 'foo', direction: 'unknown', call_kind: 'graphql' });
+  });
+  test('UnusedDocParam — extractor', () => {
+    expect(extractParams('UnusedDocParam', "The parameter 'title' is defined but not used in this file."))
+      .toEqual({ param_name: 'title' });
+    expect(extractParams('UnusedDocParam', 'unparseable'))
+      .toEqual({});
+  });
+});
+
+describe('PartialCallArguments rule', () => {
+  beforeEach(() => { clearRules(); registerRules(PartialCallArgumentsRules); });
+
+  function run(message) {
+    const params = extractParams('PartialCallArguments', message);
+    return runRules({ check: 'PartialCallArguments', params, message }, {});
+  }
+
+  test('required + render → required_render with `success: success` example', () => {
+    const r = run('Required parameter success must be passed to render call');
+    expect(r.rule_id).toBe('PartialCallArguments.required_render');
+    expect(r.hint_md).toContain('forward caller');
+    expect(r.hint_md).toMatch(/render '[^']+', success: success/);
+    expect(r.confidence).toBe(0.7);
+    expect(r.see_also.args.domain).toBe('partials');
+  });
+
+  test('required + function → required_function with `function r = ...` example', () => {
+    const r = run('Required parameter key must be passed to function call');
+    expect(r.rule_id).toBe('PartialCallArguments.required_function');
+    expect(r.hint_md).toMatch(/function r = '[^']+', key: key/);
+    expect(r.see_also.args.domain).toBe('commands');
+  });
+
+  test('unknown + render → unknown_render with three-option (drop / declare / rename)', () => {
+    const r = run('Unknown parameter params passed to render call');
+    expect(r.rule_id).toBe('PartialCallArguments.unknown_render');
+    expect(r.hint_md).toContain('Drop');
+    expect(r.hint_md).toContain('Declare');
+    expect(r.hint_md).toContain('Rename');
+    expect(r.fixes[0].description).toMatch(/[Mm]odule-owned/);
+  });
+
+  test('unknown + function → unknown_function', () => {
+    const r = run('Unknown parameter from passed to function call');
+    expect(r.rule_id).toBe('PartialCallArguments.unknown_function');
+  });
+
+  test('cross-references the sibling Missing*Arguments check', () => {
+    const r = run('Required parameter success must be passed to render call');
+    expect(r.hint_md).toContain('MissingRenderPartialArguments');
+  });
+
+  test('default fallback when extractor produces no params', () => {
+    const r = run('Some new diagnostic shape');
+    expect(r.rule_id).toBe('PartialCallArguments.default');
+    expect(r.confidence).toBeLessThanOrEqual(0.5);
+  });
+});
+
+describe('GraphQLVariablesCheck rule', () => {
+  beforeEach(() => { clearRules(); registerRules(GraphQLVariablesCheckRules); });
+
+  // Minimal fixture: one page that calls a graphql operation with two
+  // declared variables. Graph maps page path → graphql_calls; graphql
+  // node carries the args list.
+  const graph = buildFactGraph({
+    pages: {
+      'idx': {
+        path: 'app/views/pages/contact.liquid',
+        slug: 'contact',
+        method: 'post',
+        renders: [],
+        function_calls: [],
+        graphql_calls: [{ variable: 'r', queryName: 'contact_messages/create' }],
+      },
+    },
+    partials: {}, commands: {}, queries: {},
+    graphql: {
+      'contact_messages/create': {
+        operation: 'mutation',
+        name: 'create',
+        args: [{ name: 'name', type: 'String!' }, { name: 'email', type: 'String!' }],
+        table: 'contact',
+      },
+    },
+    schema: {}, layouts: {}, translations: {}, assets: [],
+  });
+
+  test('required → ships canonical examples + signature block from graph', () => {
+    const r = runRules({
+      check: 'GraphQLVariablesCheck',
+      params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+      message: 'Required parameter name must be passed to GraphQL call',
+      file: 'app/views/pages/contact.liquid',
+    }, { graph });
+    expect(r.rule_id).toBe('GraphQLVariablesCheck.required');
+    expect(r.hint_md).toContain('contact_messages/create');
+    expect(r.hint_md).toContain('$name: String!');
+    expect(r.hint_md).toContain('$email: String!');
+    expect(r.fixes[0].description).toContain('app/graphql/contact_messages/create.graphql');
+  });
+
+  test('unknown → 3-option fix, with signature block when graph has the call', () => {
+    const r = runRules({
+      check: 'GraphQLVariablesCheck',
+      params: extractParams('GraphQLVariablesCheck', 'Unknown parameter foo passed to GraphQL call'),
+      message: 'Unknown parameter foo passed to GraphQL call',
+      file: 'app/views/pages/contact.liquid',
+    }, { graph });
+    expect(r.rule_id).toBe('GraphQLVariablesCheck.unknown');
+    expect(r.hint_md).toContain('Drop');
+    expect(r.hint_md).toContain('Declare');
+    expect(r.hint_md).toContain('Rename');
+    expect(r.hint_md).toContain('contact_messages/create');
+  });
+
+  test('signature block omitted when caller file is unknown to graph', () => {
+    const r = runRules({
+      check: 'GraphQLVariablesCheck',
+      params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+      message: 'Required parameter name must be passed to GraphQL call',
+      file: 'app/views/pages/orphan.liquid',
+    }, { graph });
+    expect(r.rule_id).toBe('GraphQLVariablesCheck.required');
+    expect(r.hint_md).not.toContain('GraphQL operation(s) called');
+  });
+
+  test('default fallback', () => {
+    const r = runRules({
+      check: 'GraphQLVariablesCheck',
+      params: extractParams('GraphQLVariablesCheck', 'something obscure'),
+      message: 'something obscure',
+    }, {});
+    expect(r.rule_id).toBe('GraphQLVariablesCheck.default');
+  });
+
+  // Repro for the DEMO 2026-04-27 regression spiral. When the project
+  // graph reports the file's graphql call with source_kind=liquid_multiline_truncated,
+  // the parser_blind_spot sub-rule must fire BEFORE .required and steer the
+  // agent at the syntactic root cause.
+  describe('parser_blind_spot — multi-line truncation', () => {
+    const truncatedGraph = buildFactGraph({
+      pages: {},
+      partials: {},
+      commands: {
+        'app/lib/commands/contacts/create.liquid': {
+          path: 'app/lib/commands/contacts/create.liquid',
+          renders: [],
+          function_calls: [],
+          graphql_calls: [{
+            variable: 'result',
+            queryName: 'contacts/create',
+            args: [],
+            source_kind: 'liquid_multiline_truncated',
+          }],
+        },
+      },
+      queries: {},
+      graphql: {
+        'contacts/create': {
+          operation: 'mutation',
+          name: 'create',
+          args: [
+            { name: 'name', type: 'String!' },
+            { name: 'email', type: 'String!' },
+          ],
+          table: 'contact',
+        },
+      },
+      schema: {}, layouts: {}, translations: {}, assets: [],
+    });
+
+    test('fires before .required when graph flags the call truncated', () => {
+      const r = runRules({
+        check: 'GraphQLVariablesCheck',
+        params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+        message: 'Required parameter name must be passed to GraphQL call',
+        file: 'app/lib/commands/contacts/create.liquid',
+      }, { graph: truncatedGraph });
+      expect(r.rule_id).toBe('GraphQLVariablesCheck.parser_blind_spot');
+      expect(r.hint_md).toContain('parser cannot see it');
+      expect(r.hint_md).toContain('Fix the syntax');
+      expect(r.hint_md).toContain('contacts/create');
+      expect(r.confidence).toBe(0.95);
+    });
+
+    test('does NOT fire for direction=unknown — only required suffers from this blind spot', () => {
+      const r = runRules({
+        check: 'GraphQLVariablesCheck',
+        params: extractParams('GraphQLVariablesCheck', 'Unknown parameter foo passed to GraphQL call'),
+        message: 'Unknown parameter foo passed to GraphQL call',
+        file: 'app/lib/commands/contacts/create.liquid',
+      }, { graph: truncatedGraph });
+      expect(r.rule_id).toBe('GraphQLVariablesCheck.unknown');
+    });
+
+    test('falls through to .required when the call is NOT truncated', () => {
+      const okGraph = buildFactGraph({
+        pages: {},
+        partials: {},
+        commands: {
+          'app/lib/commands/contacts/create.liquid': {
+            path: 'app/lib/commands/contacts/create.liquid',
+            renders: [],
+            function_calls: [],
+            graphql_calls: [{
+              variable: 'result',
+              queryName: 'contacts/create',
+              args: ['name', 'email'],
+              source_kind: 'tag',
+            }],
+          },
+        },
+        queries: {},
+        graphql: {
+          'contacts/create': {
+            operation: 'mutation', name: 'create',
+            args: [{ name: 'name', type: 'String!' }, { name: 'email', type: 'String!' }],
+            table: 'contact',
+          },
+        },
+        schema: {}, layouts: {}, translations: {}, assets: [],
+      });
+      const r = runRules({
+        check: 'GraphQLVariablesCheck',
+        params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+        message: 'Required parameter name must be passed to GraphQL call',
+        file: 'app/lib/commands/contacts/create.liquid',
+      }, { graph: okGraph });
+      expect(r.rule_id).toBe('GraphQLVariablesCheck.required');
+    });
+
+    test('falls through to .required when the file is not in the graph', () => {
+      const r = runRules({
+        check: 'GraphQLVariablesCheck',
+        params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+        message: 'Required parameter name must be passed to GraphQL call',
+        file: 'app/views/pages/orphan.liquid',
+      }, { graph: truncatedGraph });
+      expect(r.rule_id).toBe('GraphQLVariablesCheck.required');
+    });
+
+    test('safe when no graph is available (degrades to .required)', () => {
+      const r = runRules({
+        check: 'GraphQLVariablesCheck',
+        params: extractParams('GraphQLVariablesCheck', 'Required parameter name must be passed to GraphQL call'),
+        message: 'Required parameter name must be passed to GraphQL call',
+        file: 'app/lib/commands/contacts/create.liquid',
+      }, {});
+      expect(r.rule_id).toBe('GraphQLVariablesCheck.required');
+    });
+  });
+});
+
+describe('UnusedDocParam rule', () => {
+  beforeEach(() => { clearRules(); registerRules(UnusedDocParamRules); });
+
+  test('lone partial (zero callers in graph) → safer to remove, higher confidence', () => {
+    const graph = buildFactGraph({
+      pages: {}, partials: {
+        'shared/orphan': { path: 'app/views/partials/shared/orphan.liquid', params: ['title'], renders: [], function_calls: [], rendered_by: [] },
+      },
+      commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [],
+    });
+    const r = runRules({
+      check: 'UnusedDocParam',
+      params: extractParams('UnusedDocParam', "The parameter 'title' is defined but not used in this file."),
+      message: "The parameter 'title' is defined but not used in this file.",
+      file: 'app/views/partials/shared/orphan.liquid',
+    }, { graph });
+    expect(r.rule_id).toBe('UnusedDocParam.default');
+    expect(r.confidence).toBe(0.8);
+    expect(r.fixes[0].description).toMatch(/option B \(remove `@param title`[^)]*\) is safe/);
+  });
+
+  test('partial with callers → lower confidence, warns about contract change', () => {
+    const graph = buildFactGraph({
+      pages: {
+        'idx': { path: 'app/views/pages/index.liquid', renders: ['shared/card'], render_calls: [{ partial: 'shared/card', args: ['title'] }], function_calls: [] },
+      },
+      partials: {
+        'shared/card': { path: 'app/views/partials/shared/card.liquid', params: ['title'], renders: [], function_calls: [], rendered_by: [] },
+      },
+      commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {}, translations: {}, assets: [],
+    });
+    const r = runRules({
+      check: 'UnusedDocParam',
+      params: extractParams('UnusedDocParam', "The parameter 'title' is defined but not used in this file."),
+      message: "The parameter 'title' is defined but not used in this file.",
+      file: 'app/views/partials/shared/card.liquid',
+    }, { graph });
+    expect(r.rule_id).toBe('UnusedDocParam.default');
+    expect(r.confidence).toBe(0.65);
+    expect(r.hint_md).toContain('caller(s) reference this file');
+    expect(r.fixes[0].description).toContain('caller(s) reference this file');
+  });
+
+  test('no graph / file → degraded but functional', () => {
+    const r = runRules({
+      check: 'UnusedDocParam',
+      params: extractParams('UnusedDocParam', "The parameter 'foo' is defined but not used in this file."),
+      message: "The parameter 'foo' is defined but not used in this file.",
+    }, {});
+    expect(r.rule_id).toBe('UnusedDocParam.default');
+    expect(r.hint_md).toContain('Caller count unknown');
+    expect(r.hint_md).toContain('platformos_references');
+  });
+
+  test('hint references the pipeline pre-suppression', () => {
+    const r = runRules({
+      check: 'UnusedDocParam',
+      params: extractParams('UnusedDocParam', "The parameter 'foo' is defined but not used in this file."),
+      message: "The parameter 'foo' is defined but not used in this file.",
+    }, {});
+    // The diagnosis emphasises that named-arg use in this file is already
+    // suppressed upstream — surviving emits are real dead declarations.
+    expect(r.hint_md).toContain('pipeline already suppresses');
+  });
+});
diff --git a/tests/unit/rules/TranslationKeyExists.test.js b/tests/unit/rules/TranslationKeyExists.test.js
index 4c8429b..9ae6a47 100644
--- a/tests/unit/rules/TranslationKeyExists.test.js
+++ b/tests/unit/rules/TranslationKeyExists.test.js
@@ -118,3 +118,161 @@ describe('TranslationKeyExists — edge cases', () => {
     expect(runRules(diag, facts)).toBeNull();
   });
 });
+
+// Realistic translations shape — what `flattenYaml` actually emits when the
+// YAML root is `en:` (the platformOS-required wrapper). Every key carries
+// the locale prefix.
+const realisticGraph = buildFactGraph({
+  pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {},
+  translations: {
+    en: {
+      'en.landing.problem.items': ['a', 'b'],
+      'en.landing.problem.title': 'Problem',
+      'en.landing.proof.title': 'Proof',
+      'en.app.user.title': 'User',
+      'en.app.user.name': 'Name',
+    },
+  },
+  assets: [],
+});
+const realisticFacts = { graph: realisticGraph };
+
+describe('TranslationKeyExists.suggest_nearest — locale-prefix correctness', () => {
+  test('hint emits bare keys (no `en.` prefix) for graph keys built from realistic YAML', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.usr.title' },
+      message: "'app.usr.title' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.suggest_nearest');
+    // Suggested key must NOT carry the `en.` prefix — Liquid's `| t` filter
+    // re-prepends the locale, so suggesting `en.app.user.title` makes the
+    // agent's call resolve to `en.en.app.user.title` and fail again.
+    expect(result.hint_md).toContain('app.user.title');
+    expect(result.hint_md).not.toMatch(/`en\.app\.user\.title`/);
+    expect(result.fixes[0].description).not.toMatch(/`en\.app\.user\.title`/);
+  });
+
+  test('hint warns explicitly against including the locale prefix', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.usr.title' },
+      message: "'app.usr.title' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.hint_md).toMatch(/do NOT include `en\.`/i);
+  });
+
+  test('agent supplied an `en.`-prefixed key — rule strips it before matching', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'en.app.usr.title' },
+      message: "'en.app.usr.title' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.suggest_nearest');
+    expect(result.hint_md).toContain('app.user.title');
+  });
+
+  test('brand-new key with no close match falls through to create_key (stricter threshold)', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.brand_new_feature.label' },
+      message: "'app.brand_new_feature.label' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.create_key');
+  });
+
+  test('one-character typo on a real key still suggests', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.user.namee' },
+      message: "'app.user.namee' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.suggest_nearest');
+    expect(result.hint_md).toContain('app.user.name');
+  });
+});
+
+describe('TranslationKeyExists.create_key — locale-prefix correctness', () => {
+  test('agent-supplied `en.` prefix is stripped before YAML emission', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'en.products.heading' },
+      message: "'en.products.heading' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.create_key');
+    // The YAML snippet nests under `products:` (NOT `en: products:`) because
+    // the file already has the `en:` root and prepending again would create
+    // `en.en.products.heading` at lookup time.
+    expect(result.hint_md).toMatch(/^products:/m);
+    expect(result.hint_md).not.toMatch(/^en:\s*\n\s*products:/m);
+  });
+
+  test('clarifies the YAML must nest under the existing `en:` root', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.greeting' },
+      message: "'app.greeting' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.fixes[0].description).toMatch(/nested under the existing `en:` root/);
+  });
+});
+
+describe('TranslationKeyExists.array_index_misuse — defensive gate', () => {
+  test('hint suggests bare arrayKey even when agent prefixed with `en.`', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'en.landing.problem.items[2]' },
+      message: "'en.landing.problem.items[2]' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse');
+    // The `assign items = '...'` snippet must NOT include `en.` — the agent
+    // would otherwise write `'en.landing.problem.items' | t` and re-trigger
+    // the prefix double-up.
+    expect(result.hint_md).toMatch(/assign items = 'landing\.problem\.items'/);
+    expect(result.hint_md).not.toMatch(/assign items = 'en\.landing\.problem\.items'/);
+  });
+
+  test('raw-message gate: catches `[N]` even when params.key extraction loses it', () => {
+    // Belt-and-suspenders: if the extractor ever drops the bracket from
+    // params.key (LSP shape change, encoding bug), the raw-message regex
+    // still routes to array_index_misuse instead of letting suggest_nearest
+    // emit a misleading parent-key suggestion.
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'landing.problem.items' },               // no [N] in params
+      message: "'landing.problem.items[3]' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse');
+  });
+
+  test('suggest_nearest is gated by raw-message regex too', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'landing.problem.items' },
+      message: "'landing.problem.items[3]' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    // Even though params.key has no [N] and is Levenshtein-close to a real key,
+    // the rule must defer to array_index_misuse via the raw-message gate.
+    expect(result.rule_id).not.toBe('TranslationKeyExists.suggest_nearest');
+  });
+
+  test('create_key is gated by raw-message regex too', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'something_unrelated' },
+      message: "'something_unrelated[0]' does not have a matching translation entry",
+    };
+    const result = runRules(diag, realisticFacts);
+    expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse');
+  });
+});
diff --git a/tests/unit/rules/module-paths.test.js b/tests/unit/rules/module-paths.test.js
new file mode 100644
index 0000000..4ad42e8
--- /dev/null
+++ b/tests/unit/rules/module-paths.test.js
@@ -0,0 +1,117 @@
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  installedModules,
+  moduleInstalled,
+  moduleCallPathsByCategory,
+  moduleCallPaths,
+} from '../../../src/core/rules/module-paths.js';
+
+let projectDir;
+
+beforeAll(() => {
+  projectDir = mkdtempSync(join(tmpdir(), 'modpaths-'));
+
+  const writeFile = (rel, content = '') => {
+    const abs = join(projectDir, rel);
+    mkdirSync(join(abs, '..'), { recursive: true });
+    writeFileSync(abs, content);
+  };
+
+  // core: lib-style layout
+  writeFile('modules/core/public/lib/commands/execute.liquid');
+  writeFile('modules/core/public/lib/commands/email/send/build.liquid');
+  writeFile('modules/core/public/lib/commands/email/send/check.liquid');
+  writeFile('modules/core/public/lib/queries/users/find.liquid');
+  writeFile('modules/core/public/lib/helpers/auth_token.liquid');
+  writeFile('modules/core/public/lib/validations/presence.liquid');
+  writeFile('modules/core/public/views/partials/widget.liquid');
+
+  // legacy: views/partials/lib layout
+  writeFile('modules/legacy/public/views/partials/lib/commands/old_create.liquid');
+  writeFile('modules/legacy/public/views/partials/lib/queries/old_find.liquid');
+  writeFile('modules/legacy/public/views/partials/banner.liquid');
+
+  // empty module
+  mkdirSync(join(projectDir, 'modules', 'empty'), { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('module-paths.installedModules', () => {
+  test('lists every directory under modules/', () => {
+    expect(installedModules(projectDir)).toEqual(['core', 'empty', 'legacy']);
+  });
+
+  test('returns [] when modules/ is missing', () => {
+    expect(installedModules('/nonexistent')).toEqual([]);
+  });
+
+  test('returns [] when projectDir is null', () => {
+    expect(installedModules(null)).toEqual([]);
+  });
+});
+
+describe('module-paths.moduleInstalled', () => {
+  test('true for present module', () => {
+    expect(moduleInstalled(projectDir, 'core')).toBe(true);
+  });
+
+  test('false for absent module', () => {
+    expect(moduleInstalled(projectDir, 'ghost')).toBe(false);
+  });
+
+  test('false on null inputs', () => {
+    expect(moduleInstalled(null, 'core')).toBe(false);
+    expect(moduleInstalled(projectDir, null)).toBe(false);
+  });
+});
+
+describe('module-paths.moduleCallPathsByCategory', () => {
+  test('groups core lib exports by category with full call_paths', () => {
+    const out = moduleCallPathsByCategory(projectDir, 'core');
+    expect(out.commands).toEqual([
+      'modules/core/commands/email/send/build',
+      'modules/core/commands/email/send/check',
+      'modules/core/commands/execute',
+    ]);
+    expect(out.queries).toEqual(['modules/core/queries/users/find']);
+    expect(out.helpers).toEqual(['modules/core/helpers/auth_token']);
+    expect(out.validations).toEqual(['modules/core/validations/presence']);
+    expect(out.partials).toContain('modules/core/widget');
+  });
+
+  test('falls back to views/partials/lib for legacy layout', () => {
+    const out = moduleCallPathsByCategory(projectDir, 'legacy');
+    expect(out.commands).toEqual(['modules/legacy/commands/old_create']);
+    expect(out.queries).toEqual(['modules/legacy/queries/old_find']);
+    expect(out.partials).toContain('modules/legacy/banner');
+  });
+
+  test('returns empty buckets for an empty module', () => {
+    const out = moduleCallPathsByCategory(projectDir, 'empty');
+    expect(out.commands).toEqual([]);
+    expect(out.queries).toEqual([]);
+    expect(out.partials).toEqual([]);
+  });
+
+  test('returns empty buckets when module is absent', () => {
+    const out = moduleCallPathsByCategory(projectDir, 'ghost');
+    expect(Object.values(out).every(v => v.length === 0)).toBe(true);
+  });
+});
+
+describe('module-paths.moduleCallPaths', () => {
+  test('flattens every callable across categories', () => {
+    const flat = moduleCallPaths(projectDir, 'core');
+    expect(flat).toContain('modules/core/commands/execute');
+    expect(flat).toContain('modules/core/queries/users/find');
+    expect(flat).toContain('modules/core/helpers/auth_token');
+    expect(flat).toContain('modules/core/validations/presence');
+    expect(flat).toContain('modules/core/widget');
+  });
+});
diff --git a/tests/unit/rules/queries.test.js b/tests/unit/rules/queries.test.js
index 79e5e37..ae965dd 100644
--- a/tests/unit/rules/queries.test.js
+++ b/tests/unit/rules/queries.test.js
@@ -2,7 +2,7 @@ import { describe, test, expect } from 'bun:test';
 import {
   nearestByLevenshtein, partialNames, commandPaths, queryPaths,
   partialsReachableFrom, dependentsOf, translationKeysForLocale,
-  schemaNames, fileExists, classifyPath,
+  schemaNames, fileExists, classifyPath, stripLocalePrefix,
 } from '../../../src/core/rules/queries.js';
 import { buildFactGraph } from '../../../src/core/project-fact-graph.js';
 
@@ -83,6 +83,55 @@ describe('node queries', () => {
   test('translationKeysForLocale returns keys', () => {
     expect(translationKeysForLocale(graph, 'en')).toContain('app.title');
   });
+
+  test('translationKeysForLocale strips the leading `.` prefix', () => {
+    // Realistic shape: `flattenYaml` over a properly-rooted en.yml emits
+    // keys prefixed with `en.` because the YAML root is the locale name.
+    const realistic = buildFactGraph({
+      pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {},
+      translations: { en: { 'en.app.user.title': 'X', 'en.app.user.name': 'Y' } },
+      assets: [],
+    });
+    const keys = translationKeysForLocale(realistic, 'en');
+    expect(keys).toContain('app.user.title');
+    expect(keys).toContain('app.user.name');
+    expect(keys.every(k => !k.startsWith('en.'))).toBe(true);
+  });
+
+  test('translationKeysForLocale leaves bare keys untouched', () => {
+    // Mis-shaped YAML (no locale wrapper) flattens to bare `app.title`.
+    // The helper should NOT invent a prefix to strip.
+    const bare = buildFactGraph({
+      pages: {}, partials: {}, commands: {}, queries: {}, graphql: {}, schema: {}, layouts: {},
+      translations: { en: { 'app.title': 'X' } },
+      assets: [],
+    });
+    expect(translationKeysForLocale(bare, 'en')).toEqual(['app.title']);
+  });
+});
+
+describe('stripLocalePrefix', () => {
+  test('strips matching `.` prefix', () => {
+    expect(stripLocalePrefix('en.app.foo', 'en')).toBe('app.foo');
+  });
+
+  test('leaves a bare key unchanged', () => {
+    expect(stripLocalePrefix('app.foo', 'en')).toBe('app.foo');
+  });
+
+  test('does not strip a different locale', () => {
+    expect(stripLocalePrefix('pl.app.foo', 'en')).toBe('pl.app.foo');
+  });
+
+  test('handles edge inputs without throwing', () => {
+    expect(stripLocalePrefix('', 'en')).toBe('');
+    expect(stripLocalePrefix(null, 'en')).toBe(null);
+    expect(stripLocalePrefix(undefined, 'en')).toBe(undefined);
+  });
+
+  test('default locale is `en`', () => {
+    expect(stripLocalePrefix('en.app.foo')).toBe('app.foo');
+  });
 });
 
 describe('partialsReachableFrom', () => {
diff --git a/tests/unit/structural-warnings.test.js b/tests/unit/structural-warnings.test.js
index 605765e..21a29ff 100644
--- a/tests/unit/structural-warnings.test.js
+++ b/tests/unit/structural-warnings.test.js
@@ -121,6 +121,71 @@ describe('structural-warnings: GraphQL in partials', () => {
   });
 });
 
+// ── Multi-line graphql in {% liquid %} block ──────────────────────────────
+
+describe('structural-warnings: GraphqlMultilineInLiquidBlock', () => {
+  // Repro for the DEMO 2026-04-27 regression spiral. Multi-line `,`
+  // continuation inside `{% liquid %}` truncates the call; LSP fires
+  // GraphQLVariablesCheck.required for every dropped arg. The structural
+  // warning surfaces the syntactic root cause loudly, before the rule layer
+  // has to disambiguate.
+  it('errors on multi-line graphql with comma continuation inside {% liquid %} block', () => {
+    const content =
+      "{% liquid\n" +
+      "graphql result = 'contacts/create',\n" +
+      "  name: shaped.name,\n" +
+      "  email: shaped.email\n" +
+      "%}";
+    const warnings = getWarnings(content, '/project/app/lib/commands/contacts/create.liquid');
+    const w = warnings.find(w => w.check === 'pos-supervisor:GraphqlMultilineInLiquidBlock');
+    expect(w).toBeDefined();
+    expect(w.severity).toBe('error');
+    expect(w.message).toContain('truncates');
+    expect(w.message).toContain('single-line tag form');
+  });
+
+  it('does NOT fire for the canonical {% graphql %} tag form', () => {
+    const content = "{% graphql result = 'op', name: shaped.name, email: shaped.email %}";
+    const warnings = getWarnings(content, '/project/app/lib/commands/x.liquid');
+    expect(warnings.some(w => w.check === 'pos-supervisor:GraphqlMultilineInLiquidBlock')).toBe(false);
+  });
+
+  it('does NOT fire for single-line graphql inside {% liquid %} block', () => {
+    const content =
+      "{% liquid\n" +
+      "graphql result = 'op', name: shaped.name, email: shaped.email\n" +
+      "%}";
+    const warnings = getWarnings(content, '/project/app/lib/commands/x.liquid');
+    expect(warnings.some(w => w.check === 'pos-supervisor:GraphqlMultilineInLiquidBlock')).toBe(false);
+  });
+
+  it('does NOT fire for multi-line graphql inside {% graphql %} tag delimiters', () => {
+    // `{%` … `%}` form parses multi-line correctly — only the {% liquid %}
+    // block continuation is truncated.
+    const content =
+      "{% graphql result = 'op',\n" +
+      "  name: shaped.name,\n" +
+      "  email: shaped.email %}";
+    const warnings = getWarnings(content, '/project/app/lib/commands/x.liquid');
+    expect(warnings.some(w => w.check === 'pos-supervisor:GraphqlMultilineInLiquidBlock')).toBe(false);
+  });
+
+  it('reports each truncated call once per occurrence', () => {
+    const content =
+      "{% liquid\n" +
+      "graphql a = 'op_a',\n" +
+      "  x: 1\n" +
+      "%}\n" +
+      "{% liquid\n" +
+      "graphql b = 'op_b',\n" +
+      "  y: 2\n" +
+      "%}";
+    const warnings = getWarnings(content, '/project/app/lib/commands/x.liquid');
+    const found = warnings.filter(w => w.check === 'pos-supervisor:GraphqlMultilineInLiquidBlock');
+    expect(found).toHaveLength(2);
+  });
+});
+
 // ── Shopify objects ────────────────────────────────────────────────────────
 
 describe('structural-warnings: Shopify objects', () => {

From f0a5425a91f4abccba07ce4bc5c503102c75fc05 Mon Sep 17 00:00:00 2001
From: Filip Klosowski 
Date: Thu, 30 Apr 2026 12:30:59 +0200
Subject: [PATCH 18/20] Knowledge base updates/CAC  decisions persistence fix

---
 .gitignore                                    |   4 +
 .serena/project.yml                           |  79 +--
 CHANGELOG.md                                  | 457 ++++++++++++++
 package.json                                  |   2 +-
 src/core/cac-config.js                        | 119 ++++
 src/core/cac-predictor.js                     | 573 ++++++++++++++++++
 src/core/diagnostic-pipeline.js               |  18 +-
 src/core/error-enricher.js                    |  34 +-
 src/core/fix-generator.js                     |  79 ++-
 src/core/rules/MissingPartial.js              |  67 ++
 src/core/rules/queries.js                     |  23 +-
 src/core/session-events.js                    |  27 +
 src/dashboard.js                              | 235 ++++++-
 src/data/checks/MissingPartial.yml            |   6 +-
 src/data/domain-gotchas.yml                   |  11 +-
 src/data/domains/commands.md                  |   2 +-
 src/data/domains/queries.md                   |   2 +-
 .../MissingPartial-invalid_lib_prefix.md      |  18 +
 src/data/knowledge.json                       |  10 +-
 src/data/modules-missing-docs.json            |   2 +-
 .../references/authentication/advanced.md     |   6 +-
 .../references/authentication/patterns.md     |   2 +-
 src/data/references/commands/README.md        | 136 +++--
 src/data/references/commands/advanced.md      | 276 +++++----
 src/data/references/commands/api.md           | 264 ++++----
 src/data/references/commands/configuration.md | 146 +++--
 src/data/references/commands/gotchas.md       | 212 ++++++-
 src/data/references/commands/patterns.md      | 307 +++++++---
 src/data/references/forms/README.md           |   2 +-
 src/data/references/graphql/gotchas.md        |   4 +-
 src/data/references/liquid/tags/gotchas.md    |  10 +-
 src/data/references/liquid/tags/patterns.md   |   4 +-
 .../references/liquid/variables/README.md     |   4 +-
 .../references/modules/core/configuration.md  |   5 +-
 src/data/references/pages/api.md              |   4 +-
 src/data/references/pages/gotchas.md          |   6 +-
 src/data/references/pages/patterns.md         |   4 +-
 src/data/references/partials/README.md        |   4 +-
 src/data/references/partials/advanced.md      |   4 +-
 src/data/references/partials/configuration.md |   6 +-
 src/data/references/partials/gotchas.md       |   4 +-
 src/data/references/partials/patterns.md      |  32 +-
 .../ok-platformos-development-guide.md        |   4 +-
 .../short-platformos-development-guide.md     |   4 +-
 src/http-server.js                            |  90 ++-
 src/server.js                                 |  35 +-
 src/tools/analyze-project.js                  |  43 +-
 src/tools/validate-code.js                    |  30 +
 ...yze-project-lib-prefix.integration.test.js |  76 ++-
 tests/integration/cac/toggle.test.js          | 178 ++++++
 tests/unit/cac-config.test.js                 | 121 ++++
 tests/unit/cac-predictor.test.js              | 563 +++++++++++++++++
 tests/unit/diagnostic-pipeline.test.js        |  73 +++
 tests/unit/error-enricher.test.js             |  40 +-
 tests/unit/rules/MissingPartial.test.js       | 109 ++++
 tests/unit/rules/queries.test.js              |  20 +-
 tests/unit/session-events.test.js             | 102 ++++
 57 files changed, 4079 insertions(+), 619 deletions(-)
 create mode 100644 src/core/cac-config.js
 create mode 100644 src/core/cac-predictor.js
 create mode 100644 src/data/hints/MissingPartial-invalid_lib_prefix.md
 create mode 100644 tests/integration/cac/toggle.test.js
 create mode 100644 tests/unit/cac-config.test.js
 create mode 100644 tests/unit/cac-predictor.test.js

diff --git a/.gitignore b/.gitignore
index 5c7adca..1001a2f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@
 /modules
 /prompts
 /.claude
+.serena
 IDEAS.md
 node_modules/
 *.log
@@ -21,3 +22,6 @@ CLAUDE.md
 # Stray test/scratch files
 /t
 /2026-*.txt
+.serena/project.yml
+.gitignore~
+.serena/project.yml
diff --git a/.serena/project.yml b/.serena/project.yml
index 381b6a8..671f431 100644
--- a/.serena/project.yml
+++ b/.serena/project.yml
@@ -3,16 +3,18 @@ project_name: "pos-mcp"
 
 
 # list of languages for which language servers are started; choose from:
-#   al                  bash                clojure             cpp                 csharp
-#   csharp_omnisharp    dart                elixir              elm                 erlang
-#   fortran             fsharp              go                  groovy              haskell
-#   haxe                java                julia               kotlin              lua
-#   markdown
-#   matlab              nix                 pascal              perl                php
-#   php_phpactor        powershell          python              python_jedi         r
-#   rego                ruby                ruby_solargraph     rust                scala
-#   swift               terraform           toml                typescript          typescript_vts
-#   vue                 yaml                zig
+#   al                  ansible             bash                clojure             cpp
+#   cpp_ccls            crystal             csharp              csharp_omnisharp    dart
+#   elixir              elm                 erlang              fortran             fsharp
+#   go                  groovy              haskell             haxe                hlsl
+#   java                json                julia               kotlin              lean4
+#   lua                 luau                markdown            matlab              msl
+#   nix                 ocaml               pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         python_ty
+#   r                   rego                ruby                ruby_solargraph     rust
+#   scala               solidity            swift               systemverilog       terraform
+#   toml                typescript          typescript_vts      vue                 yaml
+#   zig
 #   (This list may be outdated. For the current list, see values of Language enum here:
 #   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
 #   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
@@ -66,54 +68,17 @@ read_only: false
 
 # list of tool names to exclude.
 # This extends the existing exclusions (e.g. from the global configuration)
-#
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project based on the project name or path.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
-#       for example by saying that the information retrieved from a memory file is no longer correct
-#       or no longer relevant for the project.
-#  * `edit_memory`: Replaces content matching a regular expression in a memory.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_file`: Finds files in the given relative paths
-#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
-#  * `find_symbol`: Performs a global (or local) search using the language server backend.
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
-#       for clients that do not read the initial instructions when the MCP server is connected.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
-#       is relevant to the current task. You can infer whether the information
-#       is relevant from the memory file name.
-#       You should not read the same memory file multiple times in the same conversation.
-#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
-#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
-#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
-#       For JB, we use a separate tool.
-#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
-#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
-#  * `safe_delete_symbol`:
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
-#       The memory name should be meaningful.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 excluded_tools: []
 
 # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
 # This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 included_optional_tools: []
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 fixed_tools: []
 
 # list of mode names to that are always to be included in the set of active modes
@@ -124,11 +89,14 @@ fixed_tools: []
 # Set this to a list of mode names to always include the respective modes for this project.
 base_modes:
 
-# list of mode names that are to be activated by default.
-# The full set of modes to be activated is base_modes + default_modes.
-# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
 # Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
 # This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 default_modes:
 
 # initial prompt for the project. It will always be given to the LLM upon activating the project
@@ -152,3 +120,8 @@ read_only_memory_patterns: []
 # Extends the list from the global configuration, merging the two lists.
 # Example: ["_archive/.*", "_episodes/.*"]
 ignored_memory_patterns: []
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b263f43..baa1c3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,462 @@
 # Changelog
 
+## 0.7.2 — 2026-04-28
+
+CAC predictor — opt-in 4th gating axis for the diagnostic emit
+cascade (Cohen's Agentic Conjecture). Introduces a hierarchical
+empirical-Bayes scorer over the analytics store that predicts the
+probability an agent will adopt the proposed fix for a given
+diagnostic, and either suppresses or downgrades emits whose
+predicted adoption falls below a configured threshold. **Disabled
+by default**; behavior is bit-identical to 0.7.1 until an operator
+explicitly enables it from the dashboard.
+
+### Added — `src/core/cac-config.js`
+
+Persisted config at `/.pos-supervisor/cac-config.json`.
+Mirrors the `rule-overrides.js` pattern (atomic temp+rename writes,
+tolerant reads, never throws). Schema:
+`{ version: 1, enabled: false, mode: 'shadow' | 'active', threshold:
+0.30, action: 'downgrade' | 'suppress', min_samples: 5 }`.
+Out-of-range values are coerced to defaults — invalid mode strings,
+threshold outside `[0, 1]`, negative `min_samples`, etc. all silently
+fall back instead of throwing. Public API: `loadCacConfig`,
+`saveCacConfig`, `updateCacConfig`, `defaultCacConfig`,
+`VALID_MODES`, `VALID_ACTIONS`.
+
+### Added — `src/core/cac-predictor.js`
+
+Pure scoring + decision functions, decoupled from the integration
+via dependency injection (`historyProvider` / `severityProvider`):
+
+- `scoreFixHelpfulness({ rule_id, severity, file_domain, min_samples,
+  historyProvider, severityProvider })` — hierarchical
+  empirical-Bayes scorer. Tries `(rule_id, file_domain)` first, falls
+  back to `(rule_id)` alone, then `(severity)`, then a `Beta(2, 2)`
+  prior. Returns `{ p_adopted, p_lower, p_upper, n_samples, adopted,
+  feature, model }` where `feature ∈ { 'rule_id+domain', 'rule_id',
+  'severity', 'prior' }`. Re-uses `betaPosterior(...)` already
+  exported from `analytics-queries.js`.
+- `decideAction(prediction, config)` — returns `{ decision, reason }`
+  where decision is `'allow' | 'downgrade' | 'suppress'`. The
+  `feature: 'prior'` case (no signal) always allows — the predictor
+  refuses to gate when flying blind.
+- `applyCac(result, { config, analyticsStore, filePath, sessionBus,
+  log })` — the gate function. Walks `result.errors / warnings /
+  infos`, scores each diagnostic, and either passes through (shadow
+  mode) or mutates the result (active mode). Severity downgrades
+  trigger a bucket rebalance so `result.errors → result.warnings`
+  reflects the new severity. NEVER throws — predictor / store
+  failures degrade open. **Predictor only ever suppresses or
+  downgrades; never adds, never mutates fix proposals.**
+- `buildHistoryProvider(analyticsStore)` /
+  `buildSeverityProvider(analyticsStore)` — real implementations
+  that issue correlated SQL subqueries against
+  `diagnostics × outcomes` and return `{ adopted, total }`. Each
+  provider is wrapped in `safeProvide` so a failed query is treated
+  as zero samples (falls through the hierarchy).
+- In-memory ring buffer of the last 200 decisions
+  (`getRecentCacDecisions(limit)`) plus a
+  `sessionBus.emit('cac_decision', ...)` event per decision for the
+  dashboard's recent-decisions panel.
+
+### Added — validate-code integration (`src/tools/validate-code.js`)
+
+New step 12c, inserted between the existing force-disable filter
+(step 12b) and the null-hint strip (step 12). Reads
+`ctx.cacConfigState?.current.enabled` — when `false`, the call site
+short-circuits and validate-code is bit-identical to 0.7.1. When
+enabled, `applyCac(...)` is called inside a try/catch — any
+predictor failure is logged and diagnostics pass through unchanged.
+Skipped when `ctx.untracked` is set (dashboard live-console calls).
+
+### Added — server wiring (`src/server.js`)
+
+Shared mutable config ref:
+`const cacConfigState = { current: loadCacConfig(projectDir, { log })
+}`. Threaded through `ctx` so validate-code reads the latest config
+on every call. New `syncCacConfig()` callback passed to `startHttp`
+as `onCacConfigChanged` — POST to `/api/cac/config` triggers it,
+re-reading the file and refreshing the live ref without restart
+(mirrors the existing `onOverridesChanged` hot-reload pattern for
+rule overrides).
+
+### Added — HTTP endpoints (`src/http-server.js`)
+
+- **`GET /api/cac/config`** — returns
+  `{ config, defaults, valid_modes, valid_actions }` for dashboard
+  bootstrapping.
+- **`POST /api/cac/config`** — body is any subset of
+  `{ enabled, mode, threshold, action, min_samples }`. Unknown keys
+  are silently dropped; out-of-range values are coerced. Triggers
+  `onCacConfigChanged` for live-ref refresh. Returns `{ config }`
+  with the persisted state.
+- **`GET /api/cac/decisions?limit=N`** — returns
+  `{ count, decisions, summary }` from the ring buffer. `summary`
+  groups by `decision` (allow / downgrade / suppress), `feature`,
+  and `mode` for at-a-glance dashboard stats.
+
+### Added — dashboard CAC Predictor panel (`src/dashboard.js`)
+
+New panel inside the Engine Map tab, sited next to "Adaptive Mode
+Impact":
+
+- **Status badge** (OFF / SHADOW / ACTIVE) with color-coded fill.
+- **Three-state toggle** — Off / Shadow / Active. Active requires
+  `confirm()` (prevents accidental enable). Each click POSTs the
+  matching patch and re-renders.
+- **Threshold slider** (0–1, step 0.05) with live label.
+- **Action selector** (Downgrade / Suppress).
+- **min_samples** numeric input.
+- **Recent decisions** mini-table — last 30 entries with rule_id,
+  file (last two segments), feature, P(adopted), N samples,
+  decision, mode. Color-coded decision column.
+- Refresh button + auto-fetch when the Engine Map tab is opened.
+
+CSS additions (`.cac-*` classes) follow the existing AMI / em-panel
+style. Browser-side dashboard JS verified via inline `Function()`
+constructor parse — passes.
+
+### Tests
+
+- `tests/unit/cac-config.test.js` — 13 cases: defaults, missing-file
+  load, malformed-JSON tolerance, round-trip, invalid mode coerced,
+  out-of-range threshold clamped, negative `min_samples` rejected,
+  patch via `updateCacConfig`, unknown-keys dropped.
+- `tests/unit/cac-predictor.test.js` — 19 cases covering the scorer
+  hierarchy (`rule_id+domain` → `rule_id` → `severity` → `prior`),
+  the decision function (prior always allows; threshold gating with
+  both `suppress` and `downgrade` actions), the gate (disabled →
+  no-op, shadow → records-only, active → mutates result, severity
+  downgrade rebalances buckets, predictor failure passes through,
+  `.unmatched` synthesized when rule_id is missing,
+  file_domain derived from `filePath`, ring buffer caps at 200,
+  `sessionBus.emit('cac_decision', ...)` fires).
+- `tests/integration/cac/toggle.test.js` — 8 end-to-end cases
+  exercising the full HTTP + validate-code path: defaults at boot,
+  disabled is a true no-op, shadow records but doesn't modify,
+  active mode is wired without crashing, disabling resets behavior
+  immediately, garbage POST returns 400, unknown keys dropped,
+  out-of-range threshold coerced.
+
+40 new tests (32 unit + 8 integration), all green. Pre-existing
+flakes in `tests/integration/scenarios/` and the `0.7.0`-documented
+`load_development_guide` drift are unchanged by this release —
+verified by stashing the diff and re-running on a clean tree.
+
+### Safety contract
+
+The CAC layer is fully separable. Disabling it (`enabled: false` in
+config — the default) makes validate-code execute the same code path
+as 0.7.1: the integration call site is gated by a single `if
+(cacConfig?.enabled && !ctx.untracked)` check. Even when enabled,
+the predictor only ever suppresses or downgrades — it never adds
+diagnostics, never mutates fix proposals, and never throws (every
+boundary is wrapped). Schema migrations are not required — the
+analytics DB is unchanged.
+
+### Fixed — CAC decisions are now persistent
+
+Two compounding silent failures were dropping every CAC decision on
+the floor before reaching disk, leaving the dashboard's "Recent CAC
+Decisions" panel empty after every server restart even though the
+predictor was firing correctly.
+
+1. **Missing event-kind registration.** `recordDecision` called
+   `sessionBus.emit('cac_decision', …)`, but `cac_decision` was
+   absent from `KIND_SCHEMAS` in `src/core/session-events.js`.
+   `makeEvent` threw `unknown kind "cac_decision"`, the throw was
+   swallowed by the `try { sessionBus.emit(…) } catch {}` wrapper,
+   and the event never reached the NDJSON writer.
+2. **Envelope-key collision in the payload.** Even after registering
+   the schema, the in-memory ring entry carried its own `ts` field
+   that collided with `ENVELOPE_KEYS` in `makeEvent`, so the next
+   gate would have thrown `reserved envelope key "ts"` and been
+   swallowed too.
+
+Both fixes are in this release:
+
+- `src/core/session-events.js` — added `CacDecisionPayload` (typed
+  enums for `feature` / `decision` / `mode` / `severity`, nullable
+  probability fields for the no-signal `prior` case), registered as
+  `cac_decision` in `KIND_SCHEMAS`. Pinned by 6 new tests covering
+  happy path, the `prior` shape with null probabilities, the `ts`
+  envelope-collision regression, an unknown-decision rejection, and
+  full NDJSON roundtrip.
+- `src/core/cac-predictor.js::recordDecision` — compute `ts` once,
+  pass it as the `emit(kind, payload, ts)` third argument, strip
+  `ts` from the payload. Refactored ring push into `pushRingEntry`
+  shared by live emits and the rehydrator. Added defensive `?? null`
+  on optional payload fields so `.nullable()` schema constraints
+  hold even for malformed callers. Bus-failure regression test
+  asserts a thrown emit no longer drops the in-memory ring entry.
+
+### Added — CAC decision rehydration on startup
+
+The 200-entry `recentDecisions` ring lives in module-level memory and
+was previously never read from disk on boot, so the dashboard panel
+started empty even when prior sessions' NDJSON logs contained
+hundreds of decisions. New layer:
+
+- `loadRecentCacDecisions(sessionsDir, limit)` — pure function. Lists
+  `/session-*` subdirectories newest-first (session ids
+  are ISO timestamps, so lexical sort matches chronological), peeks
+  each line via cheap `JSON.parse` for `kind === 'cac_decision'`
+  before paying the full `readEvent` Zod cost, sorts the surviving
+  entries by `ts` ascending, trims to `limit`. Tolerates corrupt
+  JSON, malformed payloads, future-version events, missing files,
+  and an absent sessions directory — every error path returns `[]`
+  so a broken log can never block server boot. Overscan caps I/O at
+  `2 × limit` candidates across recent sessions.
+- `rehydrateRecentCacDecisions(sessionsDir, limit)` — replaces the
+  ring contents and returns the count. Idempotent; safe to call
+  before any live emits.
+- `src/server.js` — wired immediately after `syncCacConfig()` (uses
+  the existing `sessionsDir` declared above, no new globals). Logs
+  `cac-predictor: rehydrated N decision(s) from prior sessions` only
+  when N > 0; runs even when the predictor is disabled so flipping
+  it on later in the session doesn't show an empty audit trail.
+  Try/catch wrapped — boot continues unconditionally on I/O failure.
+
+13 new tests cover missing dir, empty dir, single-session reads,
+mixed-kind sessions, corrupt JSON / partial events / future-version
+lines, multi-session chronological merge, limit clamp + most-recent
+semantics, idempotence, and ring clearing when the sessions dir is
+empty.
+
+End-to-end verified on a real project: validate_code on a broken
+file produced 2 errors → 2 `cac_decision` lines persisted to
+`events.ndjson` → server restart → log line `rehydrated 2
+decision(s) from prior sessions` → `/api/cac/decisions` returned
+both entries with their original session timestamps preserved.
+
+### Fixed — `function`/`graphql` tag `lib/` prefix is invalid, never optional
+
+platformOS resolves `function` tag paths under the partial search
+paths declared by `@platformos/platformos-common`:
+`FILE_TYPE_DIRS[Partial] = ['views/partials', 'lib']` joined under
+`app/`. So `'commands/X'` resolves to `app/lib/commands/X.liquid`,
+and `'lib/commands/X'` resolves to `app/lib/lib/commands/X.liquid`
+— a directory that never exists in any sane project. The literal
+`lib/` prefix is **invalid**, not optional. The `graphql` tag uses
+a different search path (`['graphql', 'graph_queries']` under
+`app/`), so `'lib/queries/X'` in a `{% graphql %}` tag is doubly
+wrong.
+
+Pos-supervisor was systematically encoding the wrong assumption in
+five places — and worse, the fix-generator and rule engine were
+**suppressing the LSP's correct `MissingPartial` diagnostic** by
+stripping the `lib/` prefix before the disk check, so the agent
+saw "no problem" while platformOS would 500 at runtime. Compounded
+by ~25 documentation files (hints, references, knowledge.json,
+domain-gotchas) that listed `lib/commands/` as the canonical call
+form, training every agent reading those docs to write broken code.
+
+#### Code fixes
+
+- `src/core/diagnostic-pipeline.js::resolveMissingPartialPaths` —
+  removed the `name.replace(/^lib\//, '')` call. Now mirrors the
+  upstream `DocumentsLocator` exactly, returning candidate paths
+  under `app/views/partials/` and `app/lib/` verbatim. The LSP's
+  `MissingPartial` for `lib/commands/X` is no longer suppressed.
+- `src/tools/analyze-project.js` — same `replace(/^lib\//, '')`
+  removed from the function-call resolver. `app/lib/${fc.path}.liquid`
+  is now constructed directly, so `'lib/commands/X'` correctly
+  resolves to `app/lib/lib/commands/X.liquid` in the error message
+  and surfaces the bug to the agent. Also extended the iteration to
+  `commands` / `queries` / `layouts` `function_calls` (previously
+  only `pages` and `partials` were checked, so a wrong call inside
+  a multi-phase command's orchestrator slipped through unchecked).
+- `src/core/rules/queries.js::classifyPath` — returns
+  `{ type: 'invalid_lib_prefix', path: null, correctedName }` for
+  `lib/commands/` / `lib/queries/` instead of stripping. Existing
+  rules already gate on `path` truthiness, so `file_exists` /
+  `suggest_nearest` / `create_file` correctly skip these.
+- `src/core/rules/MissingPartial.js` — added rule
+  `MissingPartial.invalid_lib_prefix` at priority 5 (beats every
+  other branch). Emits a `text_edit` fix using the LSP positions
+  to swap the quoted reference for its `lib/`-stripped form, with
+  a guidance fallback when position fields are missing.
+- `src/core/fix-generator.js::fixMissingPartial` — handles the
+  invalid-prefix case before any other branch; emits a `text_edit`
+  with original quote-style preserved (`'` or `"`, peeked from the
+  source buffer at the diagnostic column). No longer proposes
+  creating a phantom file at `app/lib/lib/...`.
+- `src/core/error-enricher.js::detectObjectType` /
+  `buildCreatePath` — recognize `invalid_lib_prefix` as its own
+  type and route the hint renderer to the new variant template
+  with the corrected disk path.
+
+#### New hint variant
+
+`src/data/hints/MissingPartial-invalid_lib_prefix.md` — explains the
+upstream resolver semantics and prescribes "drop the prefix"
+instead of the generic "create the file" template. Renders with
+both the wrong call form (so the agent recognizes their input) and
+the corrected one, and the disk path the corrected call would
+resolve to.
+
+#### Data sweep — ~25 documentation files
+
+Every `function`-tag use of `'lib/commands/X'` and `'lib/queries/X'`
+in `src/data/` rewritten to `'commands/X'` / `'queries/X'`. Every
+`graphql`-tag use of `'lib/queries/X'` rewritten to `'X'` (graphql
+search path is `app/graphql/`, not `app/lib/queries/`). Touched
+files include `knowledge.json`, `domain-gotchas.yml`,
+`checks/MissingPartial.yml`, all `references/{partials, pages,
+commands, authentication, graphql, liquid, modules, forms}/*.md`,
+`domains/{commands, queries}.md`. Three teaching-context references
+that explicitly cite `lib/commands/X` as the wrong form
+(`Do NOT prepend lib/...`) were preserved deliberately. All YAML /
+JSON files re-validated after the sweep.
+
+#### Tests
+
+- `tests/integration/analyze-project-lib-prefix.integration.test.js`
+  — fully rewritten. The previous version pinned the inverse
+  contract (asserting `lib/commands/X` was NOT flagged when the
+  bare-form file existed); the rewrite pins the correct one
+  (`lib/commands/X` MUST be flagged with the doubled `app/lib/lib/`
+  resolution string in the error message; the bare `commands/X`
+  form is not flagged).
+- `tests/unit/rules/queries.test.js` — `classifyPath` now pinned
+  on the new `invalid_lib_prefix` shape with `correctedName`.
+- `tests/unit/rules/MissingPartial.test.js` — 7 new tests for the
+  `invalid_lib_prefix` rule (text_edit happy path, guidance
+  fallback when positions are missing, `lib/queries/` symmetry,
+  doesn't fire for bare `commands/X`, doesn't fire for module
+  paths, beats `create_file` even when the corrected file doesn't
+  exist on disk).
+- `tests/unit/diagnostic-pipeline.test.js` — 4 new tests for
+  `verifyMissingPartialsOnDisk` (suppresses bare-form cache lag,
+  does NOT suppress `lib/`-prefixed errors even when the bare-form
+  file exists on disk, symmetric for queries, still suppresses
+  legitimate non-`lib/` cache-lag misses).
+- `tests/unit/error-enricher.test.js` — 2 existing tests rewritten
+  to use canonical syntax; 1 new regression test pinning that the
+  invalid-prefix variant fires "drop the prefix" copy and never
+  the create-file template, with the single-`lib/` corrected disk
+  path always in the hint.
+
+Targeted: 373/373 pass across 22 touched test files. Full suite:
+2238/2243 pass — same 5 pre-existing failures from main (CRUD
+scenario timeout cascade and `load_development_guide` MANDATORY
+WORKFLOW), zero new regressions.
+
+The trigger for this work was a session report on 2026-04-29: an
+agent failed repeatedly to call commands from a page, concluded
+that path resolution was caller-relative ("two valid styles that
+look the same but behave differently"). The diagnosis was wrong
+(resolution is global, not caller-relative), but the symptom was
+real and ours — agents kept writing `lib/commands/X` because our
+docs said to, and our suppression hid the LSP's correct rejection.
+
+### Fixed — Commands domain references contradicted modules/core docs
+
+The `references/modules/core/*.md` docs were modernized for
+pos-cli 6.0.7+ (canonical syntax, app-level build/check phases,
+validators at `modules/core/lib/validations/`), but the
+parallel `references/commands/*.md` docs still showed the **legacy**
+API: phantom `modules/core/commands/build` and `modules/core/commands/check`
+helpers, an array-of-validators shape (`validators: [{...}]`)
+passed to a single check helper, validators called at the wrong
+path (`modules/core/validations/` instead of
+`modules/core/lib/validations/`), and validator argument order
+diverging from the actual `@param` order.
+
+Net effect: `domain_guide(commands, patterns)` returned a fake API
+that would 500 at runtime, while `module_info(core, patterns)`
+returned the correct one. Agents got opposite advice from the two
+tools depending on which they consulted first. A real session
+report on 2026-04-29 documented an agent following the wrong
+domain_guide and producing a non-working command file.
+
+#### Authoritative pattern (now consistent across both tools)
+
+Three files per command action: orchestrator + sibling
+`/build.liquid` + sibling `/check.liquid`. Only
+`modules/core/commands/execute` is module-level. Validators chain
+individually with `modules/core/lib/validations/` and argument
+order `c, field_name, object, [options...]`.
+
+```liquid
+{% function object = 'commands/products/create/build', object: params %}
+{% function object = 'commands/products/create/check', object: object %}
+{% function c = 'modules/core/lib/validations/presence',
+   c: c, field_name: 'title', object: object %}
+{% function object = 'modules/core/commands/execute',
+   mutation_name: 'products/create',
+   selection: 'record_create',
+   object: object %}
+```
+
+#### Files rewritten — `src/data/references/commands/`
+
+- `README.md` — minimal orchestrator example now uses the canonical
+  three-file pattern. Removed every legacy build/check reference
+  that wasn't an explicit anti-pattern callout.
+- `configuration.md` — directory tree shows
+  `.liquid` + `/build.liquid` + `/check.liquid`
+  per CRUD operation. Naming-conventions table includes the new
+  "Phase call" row. Command file template rewritten as the
+  three-file canonical layout.
+- `api.md` — fully rewritten. Removed the phantom
+  `modules/core/commands/build` and `modules/core/commands/check`
+  sections. Validator family now keyed at
+  `modules/core/lib/validations/` with the modern names
+  (`number`, `matches`, `equal`, `included`, …). New "Legacy
+  Forms — No Longer Supported" appendix lists every renamed
+  validator and the `validators: [...]` shape so existing agents
+  reading legacy docs know what to migrate.
+- `patterns.md` — fully rewritten. CRUD examples (create / update /
+  delete / event-publishing / conditional validation / error
+  display / command composition) all use the canonical
+  three-file shape with chained `lib/validations/` calls.
+- `gotchas.md` — TOP GOTCHA section explicitly framing the
+  phantom `modules/core/commands/build` / `…/check` as the most
+  common error. New entries for the wrong validator path
+  (`modules/core/validations/` vs `modules/core/lib/validations/`),
+  the legacy `validators: validators` array shape, and the new
+  argument order. Troubleshooting flowchart updated.
+- `advanced.md` — transactions / composition / custom validation /
+  uniqueness / file uploads / idempotent / debugging — all
+  rewritten to the canonical three-file shape. The transaction
+  example no longer reaches for a phantom
+  `modules/core/commands/build` for line items.
+
+#### Secondary doc sweep
+
+- `references/partials/patterns.md` — Command Partial Pattern
+  example rewritten to use `commands/products/create/build` and
+  `commands/products/create/check` (was using the phantom helpers).
+- `resources/ok-platformos-development-guide.md` and
+  `resources/short-platformos-development-guide.md` — Check Stage
+  examples updated:
+  `modules/core/validations/presence` →
+  `modules/core/lib/validations/presence`, with the canonical
+  argument order (`c, field_name, object`). The "DEPRECATED — DO
+  NOT USE" anti-pattern callout was already correct and was left
+  intact.
+- `knowledge.json` and `modules-missing-docs.json` — entry
+  `modules/core/validations/presence` (used by the
+  MetadataParamsCheck false-positive suppression list) corrected
+  to `modules/core/lib/validations/presence`. JSON files
+  re-validated.
+
+#### What was deliberately NOT changed
+
+Every reference to `modules/core/commands/build` /
+`modules/core/commands/check` / `modules/core/validations/` that
+remains in the docs is now an **anti-pattern teaching reference**:
+either inside a "DO NOT", "✗ WRONG", "Template not found",
+"Legacy shape", or `TOP GOTCHA` block. Removing those would lose
+the authoritative "this path doesn't exist; here's why" copy
+agents need when they hit the error in the wild.
+
+The authoritative `references/modules/core/*.md` docs were
+already correct and remain unchanged. The `commands` domain now
+mirrors them.
+
 ## 0.7.1 — 2026-04-28
 
 Fix for the `GraphQLVariablesCheck.required` regression spiral
diff --git a/package.json b/package.json
index 19f6f01..1662187 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@platformos/pos-supervisor",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "platformOS domain-specific MCP server for LLM agents",
   "type": "module",
   "bin": {
diff --git a/src/core/cac-config.js b/src/core/cac-config.js
new file mode 100644
index 0000000..6501e6d
--- /dev/null
+++ b/src/core/cac-config.js
@@ -0,0 +1,119 @@
+/**
+ * CAC predictor configuration — persisted at
+ * `/.pos-supervisor/cac-config.json`.
+ *
+ * The CAC (Cohen's Agentic Conjecture) layer is an OPT-IN 4th gating axis
+ * applied to diagnostics after the existing cascade
+ * (severity → static confidence → adaptive-mode → force-disable). It uses
+ * historical adoption data from the analytics store to predict the probability
+ * that an agent will adopt the proposed fix for a given diagnostic, and
+ * suppresses or downgrades emits whose predicted adoption falls below the
+ * configured threshold.
+ *
+ * Defaults: DISABLED. The validator behaves identically to versions that
+ * predate this module until an operator explicitly turns it on from the
+ * dashboard. Even when enabled, the default mode is `shadow`, which records
+ * decisions to the session bus but does not modify diagnostics.
+ *
+ * File schema (JSON):
+ *   {
+ *     "version": 1,
+ *     "enabled": false,
+ *     "mode": "shadow" | "active",
+ *     "threshold": 0.30,
+ *     "action":  "downgrade" | "suppress",
+ *     "min_samples": 5
+ *   }
+ *
+ * Reads are tolerant — a missing file or malformed JSON yields the safe
+ * default state (disabled). Writes are atomic (temp + rename) so a crash
+ * mid-save can't leave the file half-written. Mirrors `rule-overrides.js`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const FILE_VERSION = 1;
+const FILE_NAME = 'cac-config.json';
+
+export const VALID_MODES = ['shadow', 'active'];
+export const VALID_ACTIONS = ['downgrade', 'suppress'];
+
+function configPath(projectDir) {
+  return join(projectDir, '.pos-supervisor', FILE_NAME);
+}
+
+export function defaultCacConfig() {
+  return {
+    version: FILE_VERSION,
+    enabled: false,
+    mode: 'shadow',
+    threshold: 0.30,
+    action: 'downgrade',
+    min_samples: 5,
+  };
+}
+
+function coerceConfig(raw) {
+  const def = defaultCacConfig();
+  const out = { ...def };
+  if (typeof raw?.enabled === 'boolean') out.enabled = raw.enabled;
+  if (VALID_MODES.includes(raw?.mode)) out.mode = raw.mode;
+  if (VALID_ACTIONS.includes(raw?.action)) out.action = raw.action;
+  if (typeof raw?.threshold === 'number' && raw.threshold >= 0 && raw.threshold <= 1) {
+    out.threshold = raw.threshold;
+  }
+  if (Number.isInteger(raw?.min_samples) && raw.min_samples >= 0) {
+    out.min_samples = raw.min_samples;
+  }
+  return out;
+}
+
+/**
+ * Load config from disk. Never throws — on any error returns default state
+ * and calls `log` if provided. A corrupt config file must not prevent the
+ * server from starting or stop validate_code from running.
+ */
+export function loadCacConfig(projectDir, { log } = {}) {
+  const path = configPath(projectDir);
+  if (!existsSync(path)) return defaultCacConfig();
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return coerceConfig(parsed);
+  } catch (e) {
+    log?.(`cac-config: failed to parse ${path} (${e.message}); using defaults`);
+    return defaultCacConfig();
+  }
+}
+
+/**
+ * Atomic write: stage to a sibling temp file, then rename. fs rename within
+ * the same dir is atomic on POSIX. A reader during the write sees either the
+ * old file or the new — never a torn read.
+ */
+export function saveCacConfig(projectDir, state, { log } = {}) {
+  const path = configPath(projectDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const coerced = coerceConfig(state);
+  const payload = JSON.stringify(coerced, null, 2);
+  const tmp = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  try {
+    writeFileSync(tmp, payload);
+    renameSync(tmp, path);
+  } catch (e) {
+    log?.(`cac-config: save failed (${e.message})`);
+    throw e;
+  }
+  return coerced;
+}
+
+/**
+ * Patch one or more fields. Unknown fields are ignored (coerceConfig drops
+ * them). Returns the new state after persistence.
+ */
+export function updateCacConfig(projectDir, patch, { log } = {}) {
+  const current = loadCacConfig(projectDir, { log });
+  const merged = { ...current, ...patch };
+  return saveCacConfig(projectDir, merged, { log });
+}
diff --git a/src/core/cac-predictor.js b/src/core/cac-predictor.js
new file mode 100644
index 0000000..b90044a
--- /dev/null
+++ b/src/core/cac-predictor.js
@@ -0,0 +1,573 @@
+/**
+ * CAC predictor — opt-in 4th gating axis for the diagnostic emit cascade.
+ *
+ * Given a diagnostic produced by the existing pipeline (severity → static
+ * confidence → adaptive-mode kill-switch → force-disable), this module
+ * predicts the probability that an agent will adopt the proposed fix and
+ * decides whether to:
+ *   - allow the emit (prediction non-blocking),
+ *   - downgrade its severity (de-emphasize without removing it), or
+ *   - suppress it (drop entirely).
+ *
+ * The "neural" backend is a hierarchical empirical-Bayes scorer over the
+ * analytics store. It is INTENTIONALLY simple for the prototype:
+ *
+ *   1. Look up historical (rule_id, file_domain) outcomes — most specific.
+ *   2. Fall back to (rule_id) if (1) has fewer than `min_samples` outcomes.
+ *   3. Fall back to (severity) if (2) is also under-sampled.
+ *   4. If all three are under-sampled → allow (prediction has no signal).
+ *
+ * At each level we compute Beta(α, β) posteriors over `adopted / total`
+ * with a uniform prior (α = β = 2). The decision uses the posterior mean.
+ * The 95% credible interval is exposed for downstream telemetry / UI.
+ *
+ * The scorer is decoupled from the integration via a `historyProvider`
+ * dependency: the real provider queries the analytics store; tests inject a
+ * deterministic stub. This makes the gate logic unit-testable without a
+ * SQLite fixture.
+ *
+ * Safety contract — load-bearing:
+ *   - Predictor only ever SUPPRESSES or DOWNGRADES; it never adds, mutates
+ *     fix proposals, or alters params. If the gate is disabled, validate_code
+ *     behavior is bit-identical to a build without this module.
+ *   - When the gate raises (history provider crash, store unavailable), the
+ *     diagnostic is allowed through unchanged. Failures degrade open.
+ *   - In `shadow` mode, decisions are recorded for analysis but no
+ *     diagnostic is mutated. Used to A/B-validate a threshold before
+ *     flipping to `active`.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { betaPosterior } from './analytics-queries.js';
+import { getDomainFromPath } from './domain-detector.js';
+import { readEvent } from './session-events.js';
+
+const MAX_RECENT_DECISIONS = 200;
+const PRIOR_A = 2;
+const PRIOR_B = 2;
+
+const recentDecisions = [];
+
+/**
+ * The empirical-Bayes scorer. Pure function.
+ *
+ * @param {object} input
+ * @param {string} input.rule_id - Diagnostic rule_id (post-stamping).
+ * @param {string} input.severity - 'error' | 'warning' | 'info'.
+ * @param {string|null} input.file_domain - Output of getDomainFromPath, or null.
+ * @param {number} input.min_samples - Threshold below which a feature level is rejected.
+ * @param {(ruleId: string, fileDomain: string|null) => {adopted:number,total:number}} input.historyProvider
+ * @returns {{
+ *   p_adopted: number,
+ *   p_lower: number,
+ *   p_upper: number,
+ *   n_samples: number,
+ *   adopted: number,
+ *   feature: 'rule_id+domain'|'rule_id'|'severity'|'prior',
+ *   model: 'empirical_bayes_v1'
+ * }}
+ */
+export function scoreFixHelpfulness({
+  rule_id,
+  severity,
+  file_domain,
+  min_samples,
+  historyProvider,
+  severityProvider,
+}) {
+  const tries = [];
+
+  if (rule_id && file_domain) {
+    const h = safeProvide(historyProvider, rule_id, file_domain);
+    tries.push({ feature: 'rule_id+domain', ...h });
+  }
+  if (rule_id) {
+    const h = safeProvide(historyProvider, rule_id, null);
+    tries.push({ feature: 'rule_id', ...h });
+  }
+  if (severity && severityProvider) {
+    const h = safeProvide(severityProvider, severity);
+    tries.push({ feature: 'severity', ...h });
+  }
+
+  // Pick the most specific feature with enough samples; the order in `tries`
+  // reflects the hierarchy.
+  const chosen = tries.find(t => t.total >= min_samples);
+  if (!chosen) {
+    // No level passed min_samples — no signal. Fall back to the prior, which
+    // for Beta(2, 2) is mean = 0.5. The decision layer treats `prior` as a
+    // pass-through (allow).
+    return {
+      p_adopted: 0.5,
+      p_lower: 0.0,
+      p_upper: 1.0,
+      n_samples: 0,
+      adopted: 0,
+      feature: 'prior',
+      model: 'empirical_bayes_v1',
+    };
+  }
+
+  const { mean, lower95, upper95 } = betaPosterior(chosen.adopted, chosen.total, PRIOR_A, PRIOR_B);
+  return {
+    p_adopted: mean,
+    p_lower: lower95,
+    p_upper: upper95,
+    n_samples: chosen.total,
+    adopted: chosen.adopted,
+    feature: chosen.feature,
+    model: 'empirical_bayes_v1',
+  };
+}
+
+function safeProvide(provider, ...args) {
+  try {
+    const out = provider(...args);
+    return {
+      adopted: Number.isFinite(out?.adopted) ? out.adopted : 0,
+      total: Number.isFinite(out?.total) ? out.total : 0,
+    };
+  } catch {
+    return { adopted: 0, total: 0 };
+  }
+}
+
+/**
+ * Decide what to do with a diagnostic given a prediction and config.
+ * Pure function, separate from the prediction step so it can be unit-tested
+ * independently and tweaked without touching the scorer.
+ *
+ * Returns `{ decision, reason }` where decision is one of:
+ *   - 'allow':     emit unchanged
+ *   - 'downgrade': emit but reduce severity (error→warning, warning→info)
+ *   - 'suppress':  drop emit entirely
+ */
+export function decideAction(prediction, config) {
+  // No signal → always allow. The predictor refuses to gate when it's flying
+  // blind — early in adoption, before enough outcomes accumulate, this is
+  // the safe default.
+  if (prediction.feature === 'prior') {
+    return { decision: 'allow', reason: 'no_signal' };
+  }
+  if (prediction.p_adopted >= config.threshold) {
+    return { decision: 'allow', reason: 'above_threshold' };
+  }
+  // Below threshold — apply the configured action.
+  return {
+    decision: config.action === 'suppress' ? 'suppress' : 'downgrade',
+    reason: 'below_threshold',
+  };
+}
+
+/**
+ * Real history provider over the analytics store. Returns
+ * `{ adopted, total }` for a rule_id, optionally segmented by file_domain.
+ *
+ * `adopted` = count of outcomes where fix_applied = 'verbatim'.
+ * `total`   = count of outcomes for this rule_id (any fix_applied value).
+ *
+ * The file_domain filter uses LIKE patterns on `diagnostics.file` matching
+ * the same path heuristics as `domain-detector.js`. Only segments we can
+ * express cheaply in SQL are supported; unknown domains return `(0, 0)`.
+ */
+export function buildHistoryProvider(analyticsStore) {
+  if (!analyticsStore) {
+    return () => ({ adopted: 0, total: 0 });
+  }
+  return function historyProvider(ruleId, fileDomain) {
+    if (!ruleId) return { adopted: 0, total: 0 };
+    const pattern = fileDomain ? domainLikePattern(fileDomain) : null;
+    if (fileDomain && !pattern) return { adopted: 0, total: 0 };
+    try {
+      const sql = pattern
+        ? `SELECT o.fix_applied, COUNT(*) as cnt
+             FROM outcomes o
+             WHERE EXISTS (
+               SELECT 1 FROM diagnostics d
+               WHERE d.fp = o.fp
+                 AND d.hint_rule_id = ?
+                 AND d.suppressed = 0
+                 AND d.file LIKE ?
+             )
+             GROUP BY o.fix_applied`
+        : `SELECT o.fix_applied, COUNT(*) as cnt
+             FROM outcomes o
+             WHERE EXISTS (
+               SELECT 1 FROM diagnostics d
+               WHERE d.fp = o.fp
+                 AND d.hint_rule_id = ?
+                 AND d.suppressed = 0
+             )
+             GROUP BY o.fix_applied`;
+      const rows = pattern
+        ? analyticsStore.query(sql, [ruleId, pattern])
+        : analyticsStore.query(sql, [ruleId]);
+      let total = 0;
+      let adopted = 0;
+      for (const row of rows) {
+        total += row.cnt;
+        if (row.fix_applied === 'verbatim') adopted += row.cnt;
+      }
+      return { adopted, total };
+    } catch {
+      return { adopted: 0, total: 0 };
+    }
+  };
+}
+
+/**
+ * Severity-level fallback provider. Less segmentation, more samples.
+ * Used when both rule_id+domain and rule_id alone are under-sampled.
+ */
+export function buildSeverityProvider(analyticsStore) {
+  if (!analyticsStore) {
+    return () => ({ adopted: 0, total: 0 });
+  }
+  return function severityProvider(severity) {
+    try {
+      const rows = analyticsStore.query(
+        `SELECT o.fix_applied, COUNT(*) as cnt
+           FROM outcomes o
+           WHERE EXISTS (
+             SELECT 1 FROM diagnostics d
+             WHERE d.fp = o.fp
+               AND d.severity = ?
+               AND d.suppressed = 0
+           )
+           GROUP BY o.fix_applied`,
+        [severity],
+      );
+      let total = 0;
+      let adopted = 0;
+      for (const row of rows) {
+        total += row.cnt;
+        if (row.fix_applied === 'verbatim') adopted += row.cnt;
+      }
+      return { adopted, total };
+    } catch {
+      return { adopted: 0, total: 0 };
+    }
+  };
+}
+
+function domainLikePattern(domain) {
+  switch (domain) {
+    case 'commands':     return '%/lib/commands/%';
+    case 'queries':      return '%/lib/queries/%';
+    case 'pages':        return '%/views/pages/%';
+    case 'layouts':      return '%/views/layouts/%';
+    case 'partials':     return '%/views/partials/%';
+    case 'graphql':      return '%/graphql/%';
+    case 'schema':       return '%/schema/%';
+    case 'translations': return '%/translations/%';
+    default:             return null;
+  }
+}
+
+const SEVERITY_RANK = ['info', 'warning', 'error'];
+
+function downgradeSeverity(s) {
+  const i = SEVERITY_RANK.indexOf(s);
+  if (i <= 0) return 'info';
+  return SEVERITY_RANK[i - 1];
+}
+
+/**
+ * Apply the gate to a validate_code result. Mutates `result.errors`,
+ * `result.warnings`, `result.infos` in place when the gate is in `active`
+ * mode. In `shadow` mode the result is left untouched and decisions are
+ * appended to the session bus + recent-decisions ring buffer for later
+ * inspection.
+ *
+ * NEVER throws. If the predictor or store fails, the result passes through.
+ *
+ * @returns {Array} list of decisions emitted in this call (one per diagnostic
+ *                  considered). Order matches input order; useful for tests.
+ */
+export function applyCac(result, {
+  config,
+  analyticsStore,
+  filePath,
+  sessionBus,
+  log,
+  historyProvider,
+  severityProvider,
+} = {}) {
+  if (!config?.enabled) return [];
+  if (!result) return [];
+
+  const provider = historyProvider ?? buildHistoryProvider(analyticsStore);
+  const sevProvider = severityProvider ?? buildSeverityProvider(analyticsStore);
+  const fileDomain = filePath ? getDomainFromPath(filePath) : null;
+  const decisions = [];
+
+  const buckets = [
+    { name: 'errors',   arr: result.errors ?? [] },
+    { name: 'warnings', arr: result.warnings ?? [] },
+    { name: 'infos',    arr: result.infos ?? [] },
+  ];
+
+  for (const bucket of buckets) {
+    const kept = [];
+    for (const d of bucket.arr) {
+      let decision;
+      try {
+        const rule_id = d.rule_id || (d.check ? `${d.check}.unmatched` : null);
+        const severity = d.severity || bucketToSeverity(bucket.name);
+        const prediction = scoreFixHelpfulness({
+          rule_id,
+          severity,
+          file_domain: fileDomain,
+          min_samples: config.min_samples,
+          historyProvider: provider,
+          severityProvider: sevProvider,
+        });
+        decision = decideAction(prediction, config);
+        recordDecision({
+          file: filePath,
+          rule_id,
+          check: d.check,
+          severity,
+          file_domain: fileDomain,
+          prediction,
+          decision,
+          mode: config.mode,
+        }, sessionBus);
+        decisions.push({ rule_id, check: d.check, prediction, decision });
+      } catch (e) {
+        log?.(`cac-predictor: scoring failed (${e?.message ?? e}); allowing diagnostic`);
+        kept.push(d);
+        continue;
+      }
+
+      // Shadow mode: never modifies the result.
+      if (config.mode !== 'active') {
+        kept.push(d);
+        continue;
+      }
+
+      if (decision.decision === 'suppress') {
+        // drop — do not push
+        continue;
+      }
+      if (decision.decision === 'downgrade') {
+        const next = downgradeSeverity(d.severity || bucketToSeverity(bucket.name));
+        if (next !== d.severity) {
+          d.severity = next;
+          d.cac_downgraded = true;
+        }
+        kept.push(d);
+        continue;
+      }
+      kept.push(d);
+    }
+    bucket.arr.length = 0;
+    bucket.arr.push(...kept);
+  }
+
+  // Active-mode downgrades may have flipped severities; rebalance the
+  // buckets so an error→warning downgrade actually moves into result.warnings
+  // and not just gets stamped with severity:'warning' in result.errors.
+  if (config.mode === 'active') {
+    rebalanceBuckets(result);
+  }
+
+  return decisions;
+}
+
+function bucketToSeverity(name) {
+  if (name === 'errors')   return 'error';
+  if (name === 'warnings') return 'warning';
+  return 'info';
+}
+
+function rebalanceBuckets(result) {
+  const all = [
+    ...((result.errors ?? []).map(d => ({ d, defaultBucket: 'errors' }))),
+    ...((result.warnings ?? []).map(d => ({ d, defaultBucket: 'warnings' }))),
+    ...((result.infos ?? []).map(d => ({ d, defaultBucket: 'infos' }))),
+  ];
+  result.errors = [];
+  result.warnings = [];
+  result.infos = [];
+  for (const { d, defaultBucket } of all) {
+    const sev = d.severity || bucketToSeverity(defaultBucket);
+    if (sev === 'error')        result.errors.push(d);
+    else if (sev === 'warning') result.warnings.push(d);
+    else                        result.infos.push(d);
+  }
+}
+
+function recordDecision(entry, sessionBus) {
+  // The session-bus envelope owns `ts` (it's a reserved envelope key — see
+  // `session-events.js::ENVELOPE_KEYS`). Compute it once, pass it as the
+  // emit's third arg, and keep a copy on the ring entry so consumers of
+  // `getRecentCacDecisions()` see a single self-contained record without
+  // re-querying the bus.
+  const ts = new Date().toISOString();
+  const payload = {
+    file: entry.file ?? null,
+    rule_id: entry.rule_id ?? null,
+    check: entry.check ?? null,
+    severity: entry.severity,
+    file_domain: entry.file_domain ?? null,
+    p_adopted: entry.prediction?.p_adopted ?? null,
+    p_lower: entry.prediction?.p_lower ?? null,
+    p_upper: entry.prediction?.p_upper ?? null,
+    n_samples: entry.prediction?.n_samples ?? 0,
+    feature: entry.prediction?.feature ?? 'prior',
+    decision: entry.decision?.decision ?? 'allow',
+    reason: entry.decision?.reason ?? '',
+    mode: entry.mode,
+  };
+  pushRingEntry({ ts, ...payload });
+  if (sessionBus?.emit) {
+    try {
+      sessionBus.emit('cac_decision', payload, ts);
+    } catch {
+      // Persistence is best-effort. The in-memory ring already received the
+      // entry, so the dashboard still shows it within this session.
+    }
+  }
+}
+
+function pushRingEntry(entry) {
+  recentDecisions.push(entry);
+  if (recentDecisions.length > MAX_RECENT_DECISIONS) {
+    recentDecisions.splice(0, recentDecisions.length - MAX_RECENT_DECISIONS);
+  }
+}
+
+export function getRecentCacDecisions(limit = MAX_RECENT_DECISIONS) {
+  const start = Math.max(0, recentDecisions.length - limit);
+  return recentDecisions.slice(start);
+}
+
+export function clearRecentCacDecisions() {
+  recentDecisions.length = 0;
+}
+
+/**
+ * Reconstruct an in-memory ring entry from a persisted `cac_decision`
+ * envelope. The persisted shape places the timestamp on the envelope
+ * (`event.ts`) and every other field as a top-level payload key (validated
+ * by the registry). The ring entry collapses both back into a single flat
+ * object so consumers of `getRecentCacDecisions()` see a uniform record
+ * regardless of whether it came from the live emit path or from disk.
+ */
+function eventToRingEntry(event) {
+  return {
+    ts: event.ts,
+    file: event.file ?? null,
+    rule_id: event.rule_id ?? null,
+    check: event.check ?? null,
+    severity: event.severity,
+    file_domain: event.file_domain ?? null,
+    p_adopted: event.p_adopted,
+    p_lower: event.p_lower,
+    p_upper: event.p_upper,
+    n_samples: event.n_samples,
+    feature: event.feature,
+    decision: event.decision,
+    reason: event.reason,
+    mode: event.mode,
+  };
+}
+
+/**
+ * Scan one NDJSON file for `cac_decision` events and return ring-shape
+ * entries. Tolerates malformed lines (skipped silently — we don't want a
+ * single corrupt event to nuke the rehydration of an otherwise valid log).
+ *
+ * Performance shortcut: most lines won't be `cac_decision`, so peek at the
+ * `kind` field via cheap JSON.parse before paying the full Zod validation
+ * cost in `readEvent`.
+ */
+function extractCacDecisionsFromFile(filePath) {
+  if (!existsSync(filePath)) return [];
+  let content;
+  try { content = readFileSync(filePath, 'utf-8'); }
+  catch { return []; }
+  const out = [];
+  const lines = content.split('\n');
+  for (const line of lines) {
+    if (!line || !line.trim()) continue;
+    let raw;
+    try { raw = JSON.parse(line); }
+    catch { continue; }
+    if (!raw || raw.kind !== 'cac_decision') continue;
+    try {
+      const event = readEvent(line);
+      out.push(eventToRingEntry(event));
+    } catch {
+      // Malformed payload (e.g. older shape from a pre-schema version of
+      // this code). Skip — the dashboard would rather see fewer entries
+      // than crash the predictor on a corrupt line.
+    }
+  }
+  return out;
+}
+
+/**
+ * Read recent session NDJSON logs and return the last `limit`
+ * `cac_decision` entries in chronological order (oldest → newest).
+ *
+ * Scans `//events.ndjson`, sorted by directory
+ * name DESC (session ids are ISO timestamps so lexical order = chronological).
+ * Stops as soon as we have ≥ `2 × limit` candidates collected — overscan
+ * guards against the same event appearing twice across boundary cases
+ * (e.g. an in-flight session being scanned both by us and the live writer)
+ * while still bounding the I/O at the most recent few sessions.
+ *
+ * Returns [] for any non-fatal failure (missing dir, unreadable, etc.).
+ * Never throws — server startup must not be blocked by a broken sessions
+ * directory.
+ *
+ * @param {string} sessionsDir
+ * @param {number} [limit=MAX_RECENT_DECISIONS]
+ * @returns {Array}
+ */
+export function loadRecentCacDecisions(sessionsDir, limit = MAX_RECENT_DECISIONS) {
+  if (!sessionsDir || limit <= 0) return [];
+  let entries;
+  try { entries = readdirSync(sessionsDir, { withFileTypes: true }); }
+  catch { return []; }
+
+  const sessionDirs = entries
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .sort()
+    .reverse(); // newest session first (lexical = chronological)
+
+  const collected = [];
+  const overscanCap = limit * 2;
+  for (const name of sessionDirs) {
+    if (collected.length >= overscanCap) break;
+    const filePath = join(sessionsDir, name, 'events.ndjson');
+    const fromFile = extractCacDecisionsFromFile(filePath);
+    for (const e of fromFile) collected.push(e);
+  }
+
+  // Final ordering and trim. The bus envelope stamps `ts` as an ISO string;
+  // lexical compare matches chronological order. Stable: same-ts entries
+  // keep their original (file scan) order.
+  collected.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+  return collected.slice(Math.max(0, collected.length - limit));
+}
+
+/**
+ * Replace the in-memory ring with the most recent `cac_decision` entries
+ * persisted on disk. Returns the number of entries loaded so callers can
+ * log a one-line "rehydrated N from disk" startup message.
+ *
+ * Idempotent — calling twice produces the same end state. Safe to call
+ * before any live emits (server boot) but not while emits are in flight,
+ * since this overwrites the ring rather than merging.
+ */
+export function rehydrateRecentCacDecisions(sessionsDir, limit = MAX_RECENT_DECISIONS) {
+  const loaded = loadRecentCacDecisions(sessionsDir, limit);
+  recentDecisions.length = 0;
+  for (const e of loaded) recentDecisions.push(e);
+  return loaded.length;
+}
diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js
index 96109db..c29f476 100644
--- a/src/core/diagnostic-pipeline.js
+++ b/src/core/diagnostic-pipeline.js
@@ -944,14 +944,24 @@ function verifyMissingPartialsOnDisk(result, projectDir) {
   });
 }
 
+/**
+ * Mirror upstream `DocumentsLocator` partial-resolution semantics: the
+ * `function` / `render` tags resolve relative to the partial search paths
+ * declared by `@platformos/platformos-common` —
+ *   FILE_TYPE_DIRS[Partial] = ['views/partials', 'lib']
+ * — joined under `app/`. So `commands/X` is found at `app/lib/commands/X.liquid`
+ * and `lib/commands/X` would only resolve at `app/lib/lib/commands/X.liquid`
+ * (which never exists in any sane project). DO NOT strip a leading `lib/`
+ * here: doing so silently suppresses the LSP's correct MissingPartial error
+ * for the invalid prefix and steers agents toward the bug. The `.html.liquid`
+ * variant is included for legacy projects whose partials use the layout
+ * extension; upstream itself only matches `.liquid`, so this is a superset.
+ */
 function resolveMissingPartialPaths(name, projectDir) {
-  if (/(?:^|\/)commands\//.test(name) || /(?:^|\/)queries\//.test(name)) {
-    const stripped = name.replace(/^lib\//, '');
-    return [join(projectDir, 'app', 'lib', `${stripped}.liquid`)];
-  }
   return [
     join(projectDir, 'app', 'views', 'partials', `${name}.liquid`),
     join(projectDir, 'app', 'views', 'partials', `${name}.html.liquid`),
+    join(projectDir, 'app', 'lib', `${name}.liquid`),
   ];
 }
 
diff --git a/src/core/error-enricher.js b/src/core/error-enricher.js
index db3aace..43a9630 100644
--- a/src/core/error-enricher.js
+++ b/src/core/error-enricher.js
@@ -164,7 +164,9 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI
     const objType = detectObjectType(partialName);
     const createPath = buildCreatePath(objType, partialName);
     const tag = objType === 'partial' ? 'render' : 'function';
-    const hintVariant = objType === 'module' ? 'module' : null;
+    let hintVariant = null;
+    if (objType === 'module') hintVariant = 'module';
+    else if (objType === 'invalid_lib_prefix') hintVariant = 'invalid_lib_prefix';
 
     // For module paths: fetch LSP completions to show available paths.
     // For project paths: agent has project_map context — no completions needed.
@@ -197,6 +199,9 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI
     }
     if (suggestion) result.suggestion = suggestion;
 
+    const correctedName = objType === 'invalid_lib_prefix'
+      ? partialName.slice('lib/'.length)
+      : null;
     result.hint = partialName
       ? getHint(diagnostic.check, hintVariant, {
           object: objType,
@@ -204,6 +209,7 @@ export async function enrichError(diagnostic, { uri, lsp, filtersIndex, objectsI
           create_path: createPath,
           tag,
           has_suggestion: !!suggestion,
+          ...(correctedName ? { corrected_name: correctedName } : {}),
         })
       : getHint(diagnostic.check, hintVariant);
   }
@@ -482,14 +488,22 @@ function extractCompletionLabels(result) {
 function detectObjectType(name) {
   if (!name) return 'partial';
   if (name.startsWith('modules/')) return 'module';
-  if (/(?:^|\/)commands\//.test(name)) return 'command';
-  if (/(?:^|\/)queries\//.test(name)) return 'query';
+  // Literal `lib/commands/` or `lib/queries/` prefix is invalid: `function`
+  // tag paths resolve under the partial search paths, so `lib/commands/X`
+  // expands to `app/lib/lib/commands/X` which never exists. Tag separately
+  // so the hint renderer can surface "drop the prefix" instead of the
+  // generic "missing file" copy.
+  if (name.startsWith('lib/commands/') || name.startsWith('lib/queries/')) {
+    return 'invalid_lib_prefix';
+  }
+  if (name.startsWith('commands/')) return 'command';
+  if (name.startsWith('queries/')) return 'query';
   return 'partial';
 }
 
 /**
  * Build the expected disk path for a missing platformOS file.
- * @param {'partial'|'command'|'query'|'module'} type
+ * @param {'partial'|'command'|'query'|'module'|'invalid_lib_prefix'} type
  * @param {string|null} name
  * @returns {string}
  */
@@ -497,10 +511,14 @@ function buildCreatePath(type, name) {
   if (!name) return '(unknown path)';
   switch (type) {
     case 'command':
-    case 'query': {
-      // Name may come with or without lib/ prefix — normalize to avoid app/lib/lib/...
-      const stripped = name.replace(/^lib\//, '');
-      return `app/lib/${stripped}.liquid`;
+    case 'query':
+      return `app/lib/${name}.liquid`;
+    case 'invalid_lib_prefix': {
+      // The path is wrong, not the file. Show where the corrected call
+      // *would* resolve so the agent can sanity-check that the existing
+      // file is the intended target before applying the rule's text edit.
+      const corrected = name.slice('lib/'.length);
+      return `app/lib/${corrected}.liquid`;
     }
     case 'module': {
       const moduleName = name.split('/')[1] ?? name;
diff --git a/src/core/fix-generator.js b/src/core/fix-generator.js
index ee230ee..1f96938 100644
--- a/src/core/fix-generator.js
+++ b/src/core/fix-generator.js
@@ -378,19 +378,6 @@ function fixMissingPartial(diagnostic, projectDir, ast, content) {
   const partialPath = extractParams(diagnostic.check, diagnostic.message).partial ?? null;
   if (!partialPath) return null;
 
-  // Determine the correct directory based on the partial path
-  let targetPath;
-  let fileType = 'partial';
-  if (partialPath.startsWith('commands/') || partialPath.startsWith('lib/commands/')) {
-    targetPath = `app/lib/commands/${partialPath.replace(/^(lib\/)?commands\//, '')}.liquid`;
-    fileType = 'command';
-  } else if (partialPath.startsWith('queries/') || partialPath.startsWith('lib/queries/')) {
-    targetPath = `app/lib/queries/${partialPath.replace(/^(lib\/)?queries\//, '')}.liquid`;
-    fileType = 'query';
-  } else {
-    targetPath = `app/views/partials/${partialPath}.liquid`;
-  }
-
   // Module paths: never create_file — agent cannot create files inside installed modules
   if (partialPath.startsWith('modules/')) {
     if (diagnostic.suggestion) {
@@ -405,6 +392,36 @@ function fixMissingPartial(diagnostic, projectDir, ast, content) {
     };
   }
 
+  // Invalid `lib/` prefix on a function call. `function` tag paths resolve
+  // from the partial search paths (`app/views/partials/`, `app/lib/`), not
+  // project root, so `lib/commands/X` expands to `app/lib/lib/commands/X`
+  // which never exists. Emit a text_edit that strips the prefix; do NOT
+  // propose creating a phantom file at `app/lib/lib/...`.
+  if (partialPath.startsWith('lib/commands/') || partialPath.startsWith('lib/queries/')) {
+    const corrected = partialPath.slice('lib/'.length);
+    const edit = buildLibPrefixTextEdit(diagnostic, partialPath, corrected, content);
+    if (edit) return edit;
+    return {
+      type: 'guidance',
+      description:
+        `Drop the \`lib/\` prefix from \`${partialPath}\`. Function tag paths resolve from ` +
+        `\`app/lib/\`, so use \`${corrected}\` instead.`,
+    };
+  }
+
+  // Determine the correct directory based on the partial path
+  let targetPath;
+  let fileType = 'partial';
+  if (partialPath.startsWith('commands/')) {
+    targetPath = `app/lib/${partialPath}.liquid`;
+    fileType = 'command';
+  } else if (partialPath.startsWith('queries/')) {
+    targetPath = `app/lib/${partialPath}.liquid`;
+    fileType = 'query';
+  } else {
+    targetPath = `app/views/partials/${partialPath}.liquid`;
+  }
+
   // Check if file already exists — if so, don't suggest creating it again
   if (projectDir) {
     const absTarget = join(projectDir, targetPath);
@@ -427,6 +444,42 @@ function fixMissingPartial(diagnostic, projectDir, ast, content) {
   };
 }
 
+/**
+ * Build a `text_edit` fix that strips the invalid `lib/` prefix from a
+ * `function` tag call. Returns null if the diagnostic lacks the position
+ * fields the edit needs (line/column/endColumn).
+ *
+ * Quote handling: when `content` is available, peek at the source byte
+ * under `diagnostic.column` and re-emit with the same quote style the user
+ * wrote (`'` or `"`). Otherwise fall back to single-quote, which is the
+ * convention everywhere in platformOS templates and our scaffolds.
+ */
+function buildLibPrefixTextEdit(diagnostic, partialPath, corrected, content) {
+  if (diagnostic.line == null || diagnostic.column == null || diagnostic.endColumn == null) {
+    return null;
+  }
+  let quote = "'";
+  if (typeof content === 'string') {
+    const lines = content.split('\n');
+    const sourceLine = lines[diagnostic.line];
+    if (typeof sourceLine === 'string' && diagnostic.column < sourceLine.length) {
+      const ch = sourceLine[diagnostic.column];
+      if (ch === "'" || ch === '"') quote = ch;
+    }
+  }
+  return {
+    type: 'text_edit',
+    range: {
+      start: { line: diagnostic.line, character: diagnostic.column },
+      end: { line: diagnostic.endLine ?? diagnostic.line, character: diagnostic.endColumn },
+    },
+    new_text: `${quote}${corrected}${quote}`,
+    description:
+      `Drop invalid \`lib/\` prefix — function tag paths resolve from \`app/lib/\`. ` +
+      `Replace \`${partialPath}\` with \`${corrected}\`.`,
+  };
+}
+
 /**
  * Detect if a parameter name likely refers to a collection (array of items).
  * Used to generate appropriate scaffold content (iteration vs property access).
diff --git a/src/core/rules/MissingPartial.js b/src/core/rules/MissingPartial.js
index e2f498b..b9a6f74 100644
--- a/src/core/rules/MissingPartial.js
+++ b/src/core/rules/MissingPartial.js
@@ -2,6 +2,7 @@
  * MissingPartial rules — first check fully ported to rule engine.
  *
  * Priority order:
+ *    5 — invalid_lib_prefix: literal `lib/commands/` or `lib/queries/` prefix → text_edit
  *   10 — module_path: module partials → guidance + module_info see_also
  *   20 — file_exists: target exists on disk but LSP still flags → guidance
  *   30 — suggest_nearest: did-you-mean via Levenshtein on reachable partials
@@ -15,6 +16,45 @@ import {
 } from './module-paths.js';
 
 export const rules = [
+  {
+    // `function` tag paths resolve relative to the partial search paths
+    // (`app/views/partials/`, `app/lib/`), not project root, so `lib/commands/X`
+    // expands to `app/lib/lib/commands/X` which never exists. Drop the prefix
+    // — `commands/X` and `queries/X` are the canonical forms.
+    id: 'MissingPartial.invalid_lib_prefix',
+    check: 'MissingPartial',
+    priority: 5,
+    when: (diag) => {
+      const name = diag.params?.partial;
+      return !!name && (name.startsWith('lib/commands/') || name.startsWith('lib/queries/'));
+    },
+    apply: (diag) => {
+      const name = diag.params.partial;
+      const corrected = name.slice('lib/'.length);
+      const category = name.startsWith('lib/commands/') ? 'command' : 'query';
+      const hint =
+        `Drop the invalid \`lib/\` prefix from \`${name}\`. ` +
+        `\`function\` tag paths resolve from the partial search paths ` +
+        `(\`app/views/partials/\`, \`app/lib/\`) — a literal \`lib/\` prefix expands ` +
+        `to \`app/lib/lib/${corrected}\` which never exists. ` +
+        `Use \`${corrected}\` instead.`;
+
+      const fix = buildLibPrefixTextEdit(diag, name, corrected) ?? {
+        type: 'guidance',
+        description:
+          `Drop the \`lib/\` prefix from the ${category} call: replace \`${name}\` with \`${corrected}\` ` +
+          `in the \`{% function %}\` tag on line ${diag.line ?? '?'}.`,
+      };
+
+      return {
+        rule_id: 'MissingPartial.invalid_lib_prefix',
+        hint_md: hint,
+        fixes: [fix],
+        confidence: 0.95,
+      };
+    },
+  },
+
   {
     id: 'MissingPartial.module_path',
     check: 'MissingPartial',
@@ -248,6 +288,33 @@ export const rules = [
   },
 ];
 
+/**
+ * Build a `text_edit` fix that swaps a quoted partial reference for its
+ * `lib/`-stripped form. Returns null when the diagnostic lacks the position
+ * fields LSP normally provides (line/column/endColumn) — callers fall back
+ * to a guidance fix in that case.
+ *
+ * The replacement quotes with `'` (single-quote convention used throughout
+ * platformOS templates and our scaffolds). The rule engine has no access to
+ * the source buffer, so a perfect echo of the user's quote style can't be
+ * preserved here; `fix-generator.js` carries content and re-emits the fix
+ * with the correct quote when a buffer is available.
+ */
+function buildLibPrefixTextEdit(diag, name, corrected) {
+  if (diag.line == null || diag.column == null || diag.endColumn == null) return null;
+  return {
+    type: 'text_edit',
+    range: {
+      start: { line: diag.line, character: diag.column },
+      end: { line: diag.endLine ?? diag.line, character: diag.endColumn },
+    },
+    new_text: `'${corrected}'`,
+    description:
+      `Drop invalid \`lib/\` prefix — function paths resolve from \`app/lib/\`. ` +
+      `Replace \`${name}\` with \`${corrected}\`.`,
+  };
+}
+
 /**
  * Split `modules///` into its parts. The returned
  * `category` is the literal first segment after the module name (callers
diff --git a/src/core/rules/queries.js b/src/core/rules/queries.js
index 249d770..1fb4c72 100644
--- a/src/core/rules/queries.js
+++ b/src/core/rules/queries.js
@@ -103,13 +103,24 @@ export function assetNames(graph) {
 export function classifyPath(partialName) {
   if (!partialName) return { type: 'unknown', path: null };
   if (partialName.startsWith('modules/')) return { type: 'module', path: null };
-  if (partialName.startsWith('commands/') || partialName.startsWith('lib/commands/')) {
-    const stripped = partialName.replace(/^(lib\/)?commands\//, '');
-    return { type: 'command', path: `app/lib/commands/${stripped}.liquid` };
+  // `function` tag paths resolve from the partial search paths
+  // (`app/views/partials/`, `app/lib/`) per `@platformos/platformos-common`'s
+  // `DocumentsLocator`. A literal `lib/` prefix expands to `app/lib/lib/...`,
+  // which never exists. Surface this as its own type so the rule engine can
+  // emit a path-correction fix instead of silently routing it to the same
+  // bucket as the (legal) bare `commands/` / `queries/` form.
+  if (partialName.startsWith('lib/commands/') || partialName.startsWith('lib/queries/')) {
+    return {
+      type: 'invalid_lib_prefix',
+      path: null,
+      correctedName: partialName.slice('lib/'.length),
+    };
   }
-  if (partialName.startsWith('queries/') || partialName.startsWith('lib/queries/')) {
-    const stripped = partialName.replace(/^(lib\/)?queries\//, '');
-    return { type: 'query', path: `app/lib/queries/${stripped}.liquid` };
+  if (partialName.startsWith('commands/')) {
+    return { type: 'command', path: `app/lib/${partialName}.liquid` };
+  }
+  if (partialName.startsWith('queries/')) {
+    return { type: 'query', path: `app/lib/${partialName}.liquid` };
   }
   return { type: 'partial', path: `app/views/partials/${partialName}.liquid` };
 }
diff --git a/src/core/session-events.js b/src/core/session-events.js
index ff97e35..57d8c38 100644
--- a/src/core/session-events.js
+++ b/src/core/session-events.js
@@ -134,6 +134,32 @@ const LogPayload = z.object({
   message: z.string(),
 });
 
+// CAC predictor decision (one row per diagnostic considered by `applyCac`).
+// Persisted so the dashboard's "Recent CAC Decisions" panel survives restart
+// and so we can mine post-hoc whether a chosen threshold matched outcomes.
+//
+// Field shape mirrors the in-memory ring entry built by
+// `cac-predictor.js::recordDecision`, MINUS the envelope-reserved `ts` (the
+// session-bus envelope already carries the timestamp; the rehydrator copies
+// envelope.ts back onto the ring entry on read). Probability fields are
+// nullable to match the `feature: 'prior'` no-signal case where the scorer
+// returns no credible-interval bounds.
+const CacDecisionPayload = z.object({
+  file: z.string().nullable().optional(),
+  rule_id: z.string().nullable(),
+  check: z.string().nullable().optional(),
+  severity: z.enum(['info', 'warning', 'error']),
+  file_domain: z.string().nullable().optional(),
+  p_adopted: z.number().nullable(),
+  p_lower: z.number().nullable(),
+  p_upper: z.number().nullable(),
+  n_samples: z.number().int().nonnegative(),
+  feature: z.enum(['rule_id+domain', 'rule_id', 'severity', 'prior']),
+  decision: z.enum(['allow', 'downgrade', 'suppress']),
+  reason: z.string(),
+  mode: z.enum(['shadow', 'active']),
+});
+
 // Registry: kind → payload schema. Used for validation + introspection.
 export const KIND_SCHEMAS = Object.freeze({
   server_start: ServerStartPayload,
@@ -145,6 +171,7 @@ export const KIND_SCHEMAS = Object.freeze({
   tool_call: ToolCallPayload,
   validator_emit: ValidatorEmitPayload,
   log: LogPayload,
+  cac_decision: CacDecisionPayload,
 });
 
 export const KNOWN_KINDS = Object.freeze(Object.keys(KIND_SCHEMAS));
diff --git a/src/dashboard.js b/src/dashboard.js
index 4f7aba6..d509463 100644
--- a/src/dashboard.js
+++ b/src/dashboard.js
@@ -926,6 +926,34 @@ export function buildDashboardHtml() {
   .ami-input-reason { min-width: 200px; }
   .ami-input:focus { outline: none; border-color: var(--blue); }
 
+  /* ── CAC Predictor (opt-in 4th gating axis) ────────────────────────── */
+  .cac-badge { display: inline-block; padding: 2px 8px; font-size: 10px; font-weight: bold; letter-spacing: 0.5px; margin-left: 8px; vertical-align: middle; }
+  .cac-badge-off    { background: var(--surface2); color: var(--muted); }
+  .cac-badge-shadow { background: rgba(79, 195, 247, 0.18); color: var(--blue); }
+  .cac-badge-active { background: rgba(129, 199, 132, 0.20); color: var(--green); }
+  .cac-controls { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 14px; margin: 10px 0 16px; }
+  .cac-control { display: flex; flex-direction: column; gap: 4px; }
+  .cac-control > label { color: var(--muted); font-size: 9px; letter-spacing: 0.5px; }
+  .cac-toggle-row { display: flex; gap: 0; }
+  .cac-toggle-btn { flex: 1; background: var(--bg); border: 1px solid var(--border); color: var(--text); padding: 6px 8px; font-size: 11px; font-family: var(--mono); cursor: pointer; }
+  .cac-toggle-btn:hover:not(.active) { background: var(--surface); }
+  .cac-toggle-btn.active { background: var(--surface2); border-color: var(--blue); color: var(--blue); }
+  .cac-toggle-btn + .cac-toggle-btn { border-left: none; }
+  .cac-select, .cac-input-num { background: var(--bg); border: 1px solid var(--border); color: var(--text); padding: 4px 6px; font-size: 10px; font-family: var(--mono); }
+  .cac-select:focus, .cac-input-num:focus { outline: none; border-color: var(--blue); }
+  .cac-legend-tiny { color: var(--muted); font-size: 9px; font-style: italic; }
+  .cac-section-title { color: var(--text); font-size: 11px; font-weight: bold; letter-spacing: 0.5px; margin: 14px 0 6px; text-transform: uppercase; }
+  .cac-summary { display: flex; gap: 14px; flex-wrap: wrap; margin: 4px 0 10px; }
+  .cac-summary-stat { background: var(--surface); border: 1px solid var(--border); padding: 6px 10px; font-size: 10px; }
+  .cac-summary-stat .n { font-size: 14px; font-weight: bold; color: var(--text); }
+  .cac-summary-stat .l { font-size: 9px; color: var(--muted); }
+  .cac-table { width: 100%; border-collapse: collapse; font-size: 10px; font-family: var(--mono); }
+  .cac-table th { text-align: left; padding: 4px 6px; border-bottom: 1px solid var(--border); color: var(--muted); font-weight: normal; }
+  .cac-table td { padding: 4px 6px; border-bottom: 1px solid var(--border); }
+  .cac-decision-allow     { color: var(--green); }
+  .cac-decision-downgrade { color: var(--orange); }
+  .cac-decision-suppress  { color: var(--red); }
+
   /* ── Engine Map ────────────────────────────────────────────────────── */
   .em-header { margin-bottom: 16px; }
   .em-title-row { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
@@ -1564,6 +1592,57 @@ export function buildDashboardHtml() {
     
   
 
+  
+  
      
+    
      
+      
      
+        CAC Predictor
+        OFF
+        
+      
      
+      
      
+        Opt-in 4th gating axis. Predicts P(adopted | rule_id, file_domain) from
+        the analytics store and either downgrades or suppresses below-threshold
+        emits. Off by default; flip to Shadow
+        first to record decisions without modifying diagnostics, then
+        Active to apply them. Failures degrade open — a broken
+        predictor never breaks validate_code.
+      
      
+
+      
      
+        
      
+          
+          
      
+            
+            
+            
+          
      
+        
      
+        
      
+          
+          
+          
      P(adopted) below this triggers the action.
      
+        
      
+        
      
+          
+          
+        
      
+        
      
+          
+          
+          
      Skip gating until a feature has this many outcomes.
      
+        
      
+      
      
+
+      
      Recent decisions 
      
+      
      
+      
      
+    
      
+  
      
+
   
      
     
      
       
      Rule Topology
      
@@ -1666,7 +1745,7 @@ const TAB_LOADERS = {
   insights: () => { fetchInsightsData(); if (!hintsLoaded) fetchHints(); },
   analytics: () => { fetchAnalytics(); },
   toollab:  () => { if (!toolsLoaded) fetchTools(); fetchToolLab(); loadRuleChecks(); if (!suppressionsLoaded) fetchSuppressions(); },
-  engine:   () => { if (!engineMapLoaded) fetchEngineMap(); fetchAdaptiveImpact(); },
+  engine:   () => { if (!engineMapLoaded) fetchEngineMap(); fetchAdaptiveImpact(); fetchCacConfig(); fetchCacDecisions(); },
   'pos-cli': () => { if (!cliEnvsLoaded) fetchCliEnvs(); },
   // overview, activity, lsp: eagerly loaded via boot sequence / SSE
 };
@@ -6721,6 +6800,160 @@ function amiSubmitOverride(action) {
 document.getElementById('ami-add-fe-btn')?.addEventListener('click', function() { amiSubmitOverride('force_enable'); });
 document.getElementById('ami-add-fd-btn')?.addEventListener('click', function() { amiSubmitOverride('force_disable'); });
 
+// ── CAC Predictor (opt-in 4th gating axis) ─────────────────────────────────
+// Endpoints:
+//   GET  /api/cac/config       → { config, defaults, valid_modes, valid_actions }
+//   POST /api/cac/config       → patch (any subset of config fields)
+//   GET  /api/cac/decisions    → { count, decisions, summary }
+// State below mirrors the loaded config; UI re-renders on every fetch.
+let cacConfig = null;
+
+async function fetchCacConfig() {
+  try {
+    const r = await fetch(BASE + '/api/cac/config');
+    if (!r.ok) return;
+    const body = await r.json();
+    cacConfig = body.config;
+    renderCacConfig();
+  } catch (e) {
+    console.warn('CAC: fetchCacConfig failed', e);
+  }
+}
+
+async function fetchCacDecisions() {
+  try {
+    const r = await fetch(BASE + '/api/cac/decisions?limit=50');
+    if (!r.ok) return;
+    const body = await r.json();
+    renderCacDecisions(body);
+  } catch (e) {
+    console.warn('CAC: fetchCacDecisions failed', e);
+  }
+}
+
+async function mutateCacConfig(patch) {
+  try {
+    const r = await fetch(BASE + '/api/cac/config', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(patch),
+    });
+    if (!r.ok) {
+      const err = await r.json().catch(function() { return { error: 'HTTP ' + r.status }; });
+      alert('CAC config update failed: ' + (err.error || r.status));
+      return;
+    }
+    const body = await r.json();
+    cacConfig = body.config;
+    renderCacConfig();
+  } catch (e) {
+    alert('CAC config update failed: ' + e.message);
+  }
+}
+
+function renderCacConfig() {
+  if (!cacConfig) return;
+  const state = cacConfig.enabled ? cacConfig.mode : 'off';
+  const badge = document.getElementById('cac-status-badge');
+  if (badge) {
+    badge.className = 'cac-badge cac-badge-' + state;
+    badge.textContent = state.toUpperCase();
+  }
+  const offBtn = document.getElementById('cac-toggle-off');
+  const shadowBtn = document.getElementById('cac-toggle-shadow');
+  const activeBtn = document.getElementById('cac-toggle-active');
+  if (offBtn)    offBtn.classList.toggle('active', state === 'off');
+  if (shadowBtn) shadowBtn.classList.toggle('active', state === 'shadow');
+  if (activeBtn) activeBtn.classList.toggle('active', state === 'active');
+
+  const tEl = document.getElementById('cac-threshold');
+  const tLbl = document.getElementById('cac-threshold-val');
+  if (tEl)  tEl.value  = String(cacConfig.threshold);
+  if (tLbl) tLbl.textContent = Number(cacConfig.threshold).toFixed(2);
+
+  const aEl = document.getElementById('cac-action');
+  if (aEl) aEl.value = cacConfig.action;
+
+  const mEl = document.getElementById('cac-min-samples');
+  const mLbl = document.getElementById('cac-min-samples-val');
+  if (mEl)  mEl.value  = String(cacConfig.min_samples);
+  if (mLbl) mLbl.textContent = String(cacConfig.min_samples);
+}
+
+function renderCacDecisions(body) {
+  const countEl = document.getElementById('cac-decisions-count');
+  if (countEl) countEl.textContent = body.count ? '(' + body.count + ')' : '(0)';
+
+  const sumEl = document.getElementById('cac-decisions-summary');
+  if (sumEl) {
+    const s = body.summary || {};
+    sumEl.innerHTML = [
+      '
      ' + (s.allow ?? 0) + '
      Allowed
      ',
+      '
      ' + (s.downgrade ?? 0) + '
      Downgraded
      ',
+      '
      ' + (s.suppress ?? 0) + '
      Suppressed
      ',
+    ].join('');
+  }
+
+  const tEl = document.getElementById('cac-decisions-table');
+  if (!tEl) return;
+  const decisions = body.decisions || [];
+  if (decisions.length === 0) {
+    tEl.innerHTML = '
      No decisions yet. Run validate_code with the predictor enabled in Shadow or Active mode.
      ';
+    return;
+  }
+  const rows = decisions.slice().reverse().slice(0, 30).map(function(d) {
+    const p = d.p_adopted != null ? Number(d.p_adopted).toFixed(2) : '—';
+    const n = d.n_samples ?? 0;
+    const cls = 'cac-decision-' + (d.decision || 'allow');
+    const file = d.file ? escHtml(d.file.split('/').slice(-2).join('/')) : '—';
+    return ''
+      + '' + escHtml(d.rule_id || d.check || '') + ''
+      + '' + file + ''
+      + '' + escHtml(d.feature || '') + ''
+      + '' + p + ''
+      + '' + n + ''
+      + '' + escHtml(d.decision || '') + ''
+      + '' + escHtml(d.mode || '') + ''
+      + '';
+  }).join('');
+  tEl.innerHTML = ''
+    + ''
+    + '' + rows + '
      RuleFileFeatureP(adopted)NDecisionMode
      ';
+}
+
+document.getElementById('cac-toggle-off')?.addEventListener('click', function() {
+  mutateCacConfig({ enabled: false });
+});
+document.getElementById('cac-toggle-shadow')?.addEventListener('click', function() {
+  mutateCacConfig({ enabled: true, mode: 'shadow' });
+});
+document.getElementById('cac-toggle-active')?.addEventListener('click', function() {
+  if (!confirm('Switch CAC predictor to ACTIVE mode?\\n\\nIn active mode, below-threshold diagnostics will be suppressed or downgraded for every validate_code call. Make sure you have observed shadow-mode decisions first.')) return;
+  mutateCacConfig({ enabled: true, mode: 'active' });
+});
+document.getElementById('cac-threshold')?.addEventListener('change', function(e) {
+  const val = Number(e.target.value);
+  if (Number.isFinite(val)) mutateCacConfig({ threshold: val });
+});
+document.getElementById('cac-threshold')?.addEventListener('input', function(e) {
+  const lbl = document.getElementById('cac-threshold-val');
+  if (lbl) lbl.textContent = Number(e.target.value).toFixed(2);
+});
+document.getElementById('cac-action')?.addEventListener('change', function(e) {
+  mutateCacConfig({ action: e.target.value });
+});
+document.getElementById('cac-min-samples')?.addEventListener('change', function(e) {
+  const val = parseInt(e.target.value, 10);
+  if (Number.isFinite(val) && val >= 0) {
+    mutateCacConfig({ min_samples: val });
+    const lbl = document.getElementById('cac-min-samples-val');
+    if (lbl) lbl.textContent = String(val);
+  }
+});
+document.getElementById('cac-refresh-btn')?.addEventListener('click', function() {
+  fetchCacConfig();
+  fetchCacDecisions();
+});
+
 // Two-backslash sequence is deliberate: the entire dashboard JS lives inside
 // an outer template literal in buildDashboardHtml(). \\' in the source
 // collapses to \' in the emitted script, which the browser then parses as a
diff --git a/src/data/checks/MissingPartial.yml b/src/data/checks/MissingPartial.yml
index e929fc0..f90f2c6 100644
--- a/src/data/checks/MissingPartial.yml
+++ b/src/data/checks/MissingPartial.yml
@@ -2,5 +2,7 @@ name: MissingPartial
 summary: Referenced partial/command/query file does not exist
 hint:
   default: >-
-    Create the missing file. Partials: app/views/partials/. Commands: app/lib/commands/ (referenced as lib/commands/).
-    Queries: app/lib/queries/ (referenced as lib/queries/). Do NOT remove the render/function tag to silence this error.
+    Create the missing file. Partials: app/views/partials/ (referenced bare, e.g. `cards/product`).
+    Commands: app/lib/commands/ (referenced as `commands/...`). Queries: app/lib/queries/ (referenced as `queries/...`).
+    Do NOT prepend `lib/` to the call — `function` paths resolve under app/lib/, so `lib/commands/X` expands to
+    `app/lib/lib/commands/X` and never resolves. Do NOT remove the render/function tag to silence this error.
diff --git a/src/data/domain-gotchas.yml b/src/data/domain-gotchas.yml
index 4305174..7ba67c0 100644
--- a/src/data/domain-gotchas.yml
+++ b/src/data/domain-gotchas.yml
@@ -63,7 +63,8 @@ partials:
       trigger: uses_tag:graphql
       message: >-
         Do NOT run {% graphql %} in rendering partials (UI components). Fetch data in the page/command and pass results
-        via render parameters. Note: query wrappers in lib/queries/ and commands in lib/commands/ CAN use {% graphql %}.
+        via render parameters. Note: query wrappers under app/lib/queries/ and commands under app/lib/commands/ CAN use
+        {% graphql %} — invoke them via {% function r = 'queries/...' %} / {% function r = 'commands/...' %} (no `lib/` prefix).
       severity: architecture
     - id: partials_missing_args
       trigger: has_check:MissingRenderPartialArguments
@@ -140,8 +141,8 @@ commands:
     - id: commands_function_tag
       trigger: always
       message: >-
-        Pages invoke commands via {% function result = 'lib/commands/name/execute', arg: value %}. Do not call {%
-        graphql %} mutations directly from pages — use commands.
+        Pages invoke commands via {% function result = 'commands/name/execute', arg: value %} (no `lib/` prefix —
+        `function` paths resolve under app/lib/). Do not call {% graphql %} mutations directly from pages — use commands.
       severity: required
     - id: commands_declare_params
       trigger: has_check:UndefinedObject
@@ -167,8 +168,8 @@ queries:
     - id: queries_function_invoke
       trigger: always
       message: >-
-        Pages invoke queries via {% function result = 'lib/queries/name', arg: value %}. Queries are read-only; all
-        writes go through commands.
+        Pages invoke queries via {% function result = 'queries/name', arg: value %} (no `lib/` prefix — `function`
+        paths resolve under app/lib/). Queries are read-only; all writes go through commands.
       severity: architecture
     - id: queries_declare_params
       trigger: has_check:UndefinedObject
diff --git a/src/data/domains/commands.md b/src/data/domains/commands.md
index f59060b..b33b3f2 100644
--- a/src/data/domains/commands.md
+++ b/src/data/domains/commands.md
@@ -1,5 +1,5 @@
 [platformOS:commands] Commands use build/check/execute pattern: _build creates data, _check validates, _execute runs side effects.
-MUST NOT execute if _check returns errors. Invoke via function tag: {% function result = 'lib/commands/my_cmd/execute', arg: value %}
+MUST NOT execute if _check returns errors. Invoke via function tag: {% function result = 'commands/my_cmd/execute', arg: value %} (no `lib/` prefix — `function` paths resolve under app/lib/)
 Never use graphql tag to invoke a command — always use function tag.
 → domain_guide({ domain: "commands", section: "patterns" }) and domain_guide({ domain: "commands", section: "api" })
 ⚠️ MUST NOT create command files manually for CRUD resources. Run via bash:
diff --git a/src/data/domains/queries.md b/src/data/domains/queries.md
index ffdeaaa..95d1d22 100644
--- a/src/data/domains/queries.md
+++ b/src/data/domains/queries.md
@@ -1,4 +1,4 @@
 [platformOS:queries] Query files live in app/lib/queries/ — invoke via function tag, not graphql tag directly from partials.
-{% function result = 'lib/queries/my_query', arg: value %} — queries are read-only; all writes go through commands.
+{% function result = 'queries/my_query', arg: value %} (no `lib/` prefix — `function` paths resolve under app/lib/) — queries are read-only; all writes go through commands.
 Keep queries generic and reusable; business logic belongs in commands, not queries.
 For CRUD resources: run generator via bash (see schema domain header). Do NOT use generators MCP tools.
diff --git a/src/data/hints/MissingPartial-invalid_lib_prefix.md b/src/data/hints/MissingPartial-invalid_lib_prefix.md
new file mode 100644
index 0000000..4e4a798
--- /dev/null
+++ b/src/data/hints/MissingPartial-invalid_lib_prefix.md
@@ -0,0 +1,18 @@
+'{{name}}' is not a valid path: the literal `lib/` prefix is invalid.
+
+WHY — `function` tag paths resolve relative to the partial search paths declared by
+`@platformos/platformos-common` (`['app/views/partials', 'app/lib']`), not project root.
+So `{{name}}` expands to `app/lib/{{name}}`, i.e. `app/lib/lib/{{corrected_name}}`,
+which never exists. The `lib/` prefix is NOT optional — it is wrong everywhere
+(from pages, partials, commands, queries — caller location does not matter).
+
+FIX — drop the `lib/` prefix in this file:
+  {% {{tag}} ... = '{{name}}', ... %}            ← invalid
+  {% {{tag}} ... = '{{corrected_name}}', ... %}  ← correct
+
+The corrected call resolves to `{{create_path}}` — verify that file exists before
+relying on the rename. If it does not, create it (use the `scaffold` tool for a
+full feature) and re-run validate_code.
+
+MUST NOT: create a file at `app/lib/{{name}}.liquid` to satisfy the linter —
+that path is unreachable by platformOS at runtime.
diff --git a/src/data/knowledge.json b/src/data/knowledge.json
index 562adc1..e6e3e9f 100644
--- a/src/data/knowledge.json
+++ b/src/data/knowledge.json
@@ -131,7 +131,7 @@
     "MissingPartial": {
       "summary": "Referenced partial/command/query file does not exist",
       "hint": {
-        "default": "Create the missing file. Partials: app/views/partials/. Commands: app/lib/commands/ (referenced as lib/commands/). Queries: app/lib/queries/ (referenced as lib/queries/). Do NOT remove the render/function tag to silence this error."
+        "default": "Create the missing file. Partials: app/views/partials/ (referenced bare, e.g. 'cards/product'). Commands: app/lib/commands/ (referenced as 'commands/...'). Queries: app/lib/queries/ (referenced as 'queries/...'). Do NOT prepend 'lib/' to the call — 'function' paths resolve under app/lib/, so 'lib/commands/X' expands to 'app/lib/lib/commands/X' and never resolves. Do NOT remove the render/function tag to silence this error."
       }
     },
     "MissingRenderPartialArguments": {
@@ -364,7 +364,7 @@
         {
           "id": "partials_no_graphql",
           "trigger": "uses_tag:graphql",
-          "message": "Do NOT run {% graphql %} in rendering partials (UI components). Fetch data in the page/command and pass results via render parameters. Note: query wrappers in lib/queries/ and commands in lib/commands/ CAN use {% graphql %}.",
+          "message": "Do NOT run {% graphql %} in rendering partials (UI components). Fetch data in the page/command and pass results via render parameters. Note: query wrappers under app/lib/queries/ and commands under app/lib/commands/ CAN use {% graphql %} — invoke them via {% function r = 'queries/...' %} / {% function r = 'commands/...' %} (no `lib/` prefix in the call).",
           "severity": "architecture"
         },
         {
@@ -446,7 +446,7 @@
         {
           "id": "commands_function_tag",
           "trigger": "always",
-          "message": "Pages invoke commands via {% function result = 'lib/commands/name/execute', arg: value %}. Do not call {% graphql %} mutations directly from pages \u2014 use commands.",
+          "message": "Pages invoke commands via {% function result = 'commands/name/execute', arg: value %} (no `lib/` prefix \u2014 `function` paths resolve under app/lib/). Do not call {% graphql %} mutations directly from pages \u2014 use commands.",
           "severity": "required"
         },
         {
@@ -475,7 +475,7 @@
         {
           "id": "queries_function_invoke",
           "trigger": "always",
-          "message": "Pages invoke queries via {% function result = 'lib/queries/name', arg: value %}. Queries are read-only; all writes go through commands.",
+          "message": "Pages invoke queries via {% function result = 'queries/name', arg: value %} (no `lib/` prefix — `function` paths resolve under app/lib/). Queries are read-only; all writes go through commands.",
           "severity": "architecture"
         },
         {
@@ -770,7 +770,7 @@
       "modules/user/helpers/can_do",
       "modules/common-styling/forms/error_list",
       "modules/common-styling/forms/error_input_handler",
-      "modules/core/validations/presence",
+      "modules/core/lib/validations/presence",
       "modules/core/commands/execute"
     ]
   }
diff --git a/src/data/modules-missing-docs.json b/src/data/modules-missing-docs.json
index 72d51cb..186d334 100644
--- a/src/data/modules-missing-docs.json
+++ b/src/data/modules-missing-docs.json
@@ -6,7 +6,7 @@
     "modules/user/helpers/can_do",
     "modules/common-styling/forms/error_list",
     "modules/common-styling/forms/error_input_handler",
-    "modules/core/validations/presence",
+    "modules/core/lib/validations/presence",
     "modules/core/commands/execute"
   ]
 }
diff --git a/src/data/references/authentication/advanced.md b/src/data/references/authentication/advanced.md
index e0b888d..7647af0 100644
--- a/src/data/references/authentication/advanced.md
+++ b/src/data/references/authentication/advanced.md
@@ -31,7 +31,7 @@ The default permission system uses a flat role-to-actions mapping. For more comp
 Usage:
 
 ```liquid
-{% function can_edit = 'lib/helpers/can_edit_own',
+{% function can_edit = 'helpers/can_edit_own',
   requester: profile,
   do: 'products.update',
   object: product
@@ -118,7 +118,7 @@ When using an external identity provider (Google, GitHub, etc.), the flow is:
 slug: auth/callback
 ---
 {% liquid
-  function result = 'lib/commands/auth/exchange_code', code: context.params.code
+  function result = 'commands/auth/exchange_code', code: context.params.code
 
   if result.error
     include 'modules/core/helpers/redirect_to', url: '/login', alert: 'app.auth.oauth_failed'
@@ -166,7 +166,7 @@ slug: api/v1/orders
 layout: ""
 ---
 {% liquid
-  function profile = 'lib/helpers/verify_api_token'
+  function profile = 'helpers/verify_api_token'
   if profile == blank
     assign error = { "error": "unauthorized" }
     render 'api/error', status: 401, body: error
diff --git a/src/data/references/authentication/patterns.md b/src/data/references/authentication/patterns.md
index e69dd93..d90727e 100644
--- a/src/data/references/authentication/patterns.md
+++ b/src/data/references/authentication/patterns.md
@@ -90,7 +90,7 @@ slug: registrations
 method: post
 ---
 {% liquid
-  function result = 'lib/commands/registrations/create', params: context.params
+  function result = 'commands/registrations/create', params: context.params
   if result.errors != blank
     render 'registrations/form', errors: result.errors, params: context.params
     break
diff --git a/src/data/references/commands/README.md b/src/data/references/commands/README.md
index 0d34eb9..4676fb0 100644
--- a/src/data/references/commands/README.md
+++ b/src/data/references/commands/README.md
@@ -1,10 +1,18 @@
 # Commands (Business Logic)
 
-Commands encapsulate business rules in platformOS following the **build, check, execute** pattern. They provide a structured, testable approach to all create, update, and delete operations using pos-module-core helpers.
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax).
+
+Commands encapsulate business rules in platformOS following the
+**build → check → execute** pattern. They provide a structured,
+testable approach to all create / update / delete operations using the
+`pos-module-core` execute helper.
 
 ## Key Purpose
 
-Commands are the single place for business logic in a platformOS application. They enforce a strict three-stage pipeline that separates data construction, validation, and persistence. This keeps pages thin (controller-only) and partials focused on presentation.
+Commands are the single place for business logic in a platformOS
+application. They enforce a strict three-phase pipeline that
+separates data construction, validation, and persistence. This keeps
+pages thin (controller-only) and partials focused on presentation.
 
 ## When to Use
 
@@ -12,9 +20,10 @@ Commands are the single place for business logic in a platformOS application. Th
 - Validating user input before persistence
 - Encapsulating business rules that must be enforced consistently
 - Operations that should optionally trigger side effects (events)
-- Any data mutation that needs to be callable from pages, background jobs, or other commands
+- Any data mutation callable from pages, background jobs, or other commands
 
 Do NOT use commands for:
+
 - Read-only queries (use `app/lib/queries/` instead)
 - Pure presentation logic (use partials)
 - One-off data transformations with no persistence
@@ -25,58 +34,99 @@ Do NOT use commands for:
 User Request
     |
     v
-Page (Controller) --- calls ---> Command partial
-                                     |
-                           +---------+---------+
-                           |         |         |
-                         Build     Check    Execute
-                           |         |         |
-                       Construct  Validate  Persist
-                        object    fields    via GraphQL
-                           |         |         |
-                           +----+----+----+----+
-                                |         |
-                            Return     Publish
-                            result     event (optional)
+Page (Controller) --- calls ---> Command orchestrator
+                                       |
+                          +------------+------------+
+                          |            |            |
+                        Build        Check       Execute
+                       (your app)  (your app)   (modules/core/commands/execute)
+                          |            |            |
+                       Construct    Validate      Persist
+                        object      fields       via GraphQL
+                          |            |            |
+                          +-----+------+-----+------+
+                                |            |
+                            Return       Publish event
+                            result       (optional)
 ```
 
-1. **Build** -- Assemble a data object from input parameters using `assign` with hash literals and `modules/core/commands/build`.
-2. **Check** -- Validate the object against a JSON array of validators using `modules/core/commands/check`.
-3. **Execute** -- If `object.valid` is true, persist via `modules/core/commands/execute` with a GraphQL mutation.
+1. **Build** — Your `app/lib/commands///build.liquid`
+   normalizes input from the orchestrator and seeds the validation
+   contract.
+2. **Check** — Your `app/lib/commands///check.liquid`
+   chains calls to `modules/core/lib/validations/`, threading
+   the contract through each call.
+3. **Execute** — `modules/core/commands/execute` runs the GraphQL
+   mutation if `object.valid == true`.
+
+Important: there is **no** `modules/core/commands/build` and **no**
+`modules/core/commands/check`. Those phases are app-level files inside
+your own command directory. Only `commands/execute` runs at the
+module level.
 
-The result object always contains `valid` (boolean), `errors` (hash), and the original data fields.
+The result object always contains `valid` (boolean), `errors`
+(hash keyed by field name with translation-key arrays), and the
+original data fields.
 
 ## Getting Started
 
-1. Create a command file at `app/lib/commands//.liquid` (e.g., `app/lib/commands/products/create.liquid`).
-2. Implement the three stages: build, check, execute.
-3. Call from a page via `{% function result = 'lib/commands/products/create', title: title, price: price %}`.
-4. Check `result.valid` to determine success or failure.
-5. On failure, re-render the form with `result.errors` for display.
+Run the CRUD generator to scaffold the canonical layout in one
+command:
 
-Minimal command:
+```bash
+pos-cli generators run crud --resource product --include-views
+```
 
-```liquid
-{% assign object = { "title": title } %}
-{% function object = 'modules/core/commands/build', object: object %}
+This creates the orchestrator + build + check trio + GraphQL mutation
++ schema + view partials, all wired with the canonical syntax.
 
-{% assign validators = [{ "name": "presence", "property": "title" }] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
+To call the command from a page:
 
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute', mutation_name: 'products/create', selection: 'record_create', object: object %}
+```liquid
+{% function result = 'commands/products/create',
+   params: context.params.product %}
+
+{% if result.valid %}
+  {% function _ = 'modules/core/helpers/redirect_to',
+     url: '/products', notice: 'app.products.created' %}
+{% else %}
+  {% render 'products/form', product: result %}
 {% endif %}
-{% return object %}
+```
+
+Minimal orchestrator (what the generator produces):
+
+```liquid
+{% comment %} app/lib/commands/products/create.liquid {% endcomment %}
+{% doc %}
+  @param {object} params - raw input
+{% enddoc %}
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  function object = 'commands/products/create/check', object: object
+
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
+    mutation_name: 'products/create',
+    selection: 'record_create',
+    object: object
+
+  return object
+%}
 ```
 
 ## See Also
 
-- [configuration.md](configuration.md) -- File naming, directory layout, and setup conventions
-- [api.md](api.md) -- Core module helpers, validator signatures, and return types
-- [patterns.md](patterns.md) -- Common command workflows and real-world examples
-- [gotchas.md](gotchas.md) -- Common errors, limits, and troubleshooting
-- [advanced.md](advanced.md) -- Nested commands, background execution, and optimization
-- [Events & Consumers](../events-consumers/) -- Publishing events from commands
-- [Background Jobs](../background-jobs/) -- Running commands asynchronously
-- [GraphQL](../graphql/) -- Mutation files used by commands
-- [Schema](../schema/) -- Table definitions that commands operate on
+- [configuration.md](configuration.md) — File naming, directory layout, setup
+- [api.md](api.md) — Module-level runner + validator family signatures
+- [patterns.md](patterns.md) — Common command workflows (canonical examples)
+- [gotchas.md](gotchas.md) — Common errors (esp. phantom build/check)
+- [advanced.md](advanced.md) — Nested commands, background jobs, transactions
+- [modules/core/README.md](../modules/core/README.md) — pos-module-core overview
+- [Events & Consumers](../events-consumers/) — Publishing events from commands
+- [Background Jobs](../background-jobs/) — Running commands asynchronously
+- [GraphQL](../graphql/) — Mutation files used by commands
+- [Schema](../schema/) — Table definitions that commands operate on
diff --git a/src/data/references/commands/advanced.md b/src/data/references/commands/advanced.md
index 5a0b618..440f9b5 100644
--- a/src/data/references/commands/advanced.md
+++ b/src/data/references/commands/advanced.md
@@ -1,14 +1,18 @@
 # Commands -- Advanced Topics
 
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). Build/check
+> phases live in YOUR app commands, not in `modules/core/commands/`.
+
 ## Running Commands as Background Jobs
 
-Commands can be executed asynchronously using the `{% background %}` tag. This is useful for operations that do not need to return a result to the user immediately.
+Commands can be executed asynchronously using the `{% background %}`
+tag. Useful for operations that don't need to return a result to the
+user immediately.
 
 ```liquid
 {% background source_name: 'create_report', priority: 'low', max_attempts: 3 %}
-  {% function result = 'lib/commands/reports/create',
-    user_id: user_id,
-    date_range: date_range
+  {% function result = 'commands/reports/create',
+    params: { user_id: user_id, date_range: date_range }
   %}
   {% if result.valid != true %}
     {% log result.errors, type: 'error' %}
@@ -16,119 +20,171 @@ Commands can be executed asynchronously using the `{% background %}` tag. This i
 {% endbackground %}
 ```
 
-When running commands in the background, you cannot return the result to the caller. Use events or polling to communicate outcomes.
+When running commands in the background, you cannot return the result
+to the caller. Use events or polling to communicate outcomes.
 
 ## Multi-Step Commands with Transactions
 
-For operations that must succeed or fail atomically, wrap multiple mutations in a `{% transaction %}` block inside the execute stage.
+For operations that must succeed or fail atomically, wrap multiple
+mutations in a `{% transaction %}` block inside the orchestrator.
 
 ```liquid
-{% if object.valid %}
-  {% transaction %}
-    {% function object = 'modules/core/commands/execute',
-      mutation_name: 'orders/create',
+{% comment %} app/lib/commands/orders/create_with_items.liquid {% endcomment %}
+{% liquid
+  function object = 'commands/orders/create/build', object: params
+  function object = 'commands/orders/create/check', object: object
+  if object.valid == false
+    return object
+  endif
+%}
+
+{% transaction %}
+  {% function object = 'modules/core/commands/execute',
+    mutation_name: 'orders/create',
+    selection: 'record_create',
+    object: object
+  %}
+
+  {% for item in items %}
+    {% assign line_item = { order_id: object.id, product_id: item.product_id, quantity: item.quantity } %}
+    {% function line_item = 'modules/core/commands/execute',
+      mutation_name: 'order_items/create',
       selection: 'record_create',
-      object: object
+      object: line_item
     %}
+  {% endfor %}
+{% endtransaction %}
 
-    {% for item in items %}
-      {% assign line_item = { "order_id": object.id, "product_id": item.product_id, "quantity": item.quantity } %}
-      {% function line_item = 'modules/core/commands/build', object: line_item %}
-      {% function line_item = 'modules/core/commands/execute',
-        mutation_name: 'order_items/create',
-        selection: 'record_create',
-        object: line_item
-      %}
-    {% endfor %}
-  {% endtransaction %}
-{% endif %}
+{% return object %}
 ```
 
-If any mutation inside the transaction fails, all changes are rolled back.
+If any mutation inside the transaction fails, all changes are rolled
+back. Note: there's no `modules/core/commands/build` — line items
+either come pre-built from `params`, or you call your own
+`commands/order_items/create/build` partial.
 
 ## Custom Validation Logic
 
-When built-in validators are not sufficient, add custom checks after the standard check stage.
+When the built-in validators aren't sufficient, add custom checks at
+the end of your check phase, after the standard validator chain.
 
 ```liquid
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-
-{% comment %} Custom: ensure end_date is after start_date {% endcomment %}
-{% if object.valid %}
-  {% assign start = object.start_date | to_time %}
-  {% assign end = object.end_date | to_time %}
-  {% if end <= start %}
-    {% assign object = object | hash_merge: valid: false %}
-    {% assign date_error = ["must be after start date"] %}
-    {% assign errors = object.errors | hash_merge: end_date: date_error %}
-    {% assign object = object | hash_merge: errors: errors %}
-  {% endif %}
-{% endif %}
+{% comment %} app/lib/commands/events/create/check.liquid {% endcomment %}
+{% doc %}
+  @param {object} object - object from the build phase
+{% enddoc %}
+{% liquid
+  assign c = object.errors | default: empty
+
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'start_date', object: object
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'end_date', object: object
+
+  comment
+    Custom: ensure end_date is after start_date.
+    Append to the contract using the same shape validators emit:
+    { field_name: ['translation.key'] }.
+  endcomment
+  if object.start_date != blank and object.end_date != blank
+    assign start = object.start_date | to_time
+    assign finish = object.end_date | to_time
+    if finish <= start
+      assign existing = c.end_date | default: empty
+      assign c['end_date'] = existing | array_add: 'app.events.end_after_start'
+    endif
+  endif
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
-This preserves the standard error structure so callers can handle custom errors identically to built-in ones.
+This preserves the standard error structure so callers handle custom
+errors identically to built-in ones.
 
 ## Composing Commands
 
-Complex workflows can be built by calling commands from within commands. Keep each command focused on a single resource.
+Complex workflows compose by calling other orchestrators directly with
+`{% function %}`. Each composed command is a self-contained
+build → check → execute sequence.
 
 ```liquid
 {% comment %} app/lib/commands/checkout/process.liquid {% endcomment %}
-
-{% function order = 'lib/commands/orders/create',
-  user_id: user_id,
-  total: cart_total
+{% doc %}
+  @param {string} user_id
+  @param {number} cart_total
+  @param {string} payment_token
+{% enddoc %}
+{% liquid
+  function order = 'commands/orders/create',
+    params: { user_id: user_id, total: cart_total }
+
+  if order.valid
+    function payment = 'commands/payments/charge',
+      params: { order_id: order.id, amount: cart_total, token: payment_token }
+
+    if payment.valid
+      function _ = 'modules/core/commands/events/publish',
+        type: 'order_created', object: order
+      assign result = payment
+    else
+      comment Roll back the order if payment fails. endcomment
+      function _ = 'commands/orders/cancel', params: { id: order.id }
+      assign result = payment
+    endif
+  else
+    assign result = order
+  endif
+
+  return result
 %}
+```
 
-{% if order.valid %}
-  {% function payment = 'lib/commands/payments/charge',
-    order_id: order.id,
-    amount: cart_total,
-    token: payment_token
-  %}
+## Optimizing Validator Performance
 
-  {% if payment.valid %}
-    {% function _ = 'modules/core/commands/events/publish',
-      type: 'order_created',
-      object: order
-    %}
-  {% else %}
-    {% comment %} Roll back the order if payment fails {% endcomment %}
-    {% function _ = 'lib/commands/orders/cancel', id: order.id %}
-  {% endif %}
+The `uniqueness` validator issues a database query for each field it
+checks. Minimize its use and place it last in the validator chain so
+cheaper validators (presence, length, number) fail first and short-
+circuit the contract.
 
-  {% assign result = payment %}
-{% else %}
-  {% assign result = order %}
-{% endif %}
+```liquid
+{% liquid
+  assign c = object.errors | default: empty
 
-{% return result %}
-```
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'email', object: object
 
-## Optimizing Validator Performance
+  function c = 'modules/core/lib/validations/matches',
+    c: c, field_name: 'email', object: object,
+    regexp: '^[^@]+@[^@]+\.[^@]+$', allow_blank: true
 
-The `uniqueness` validator issues a database query for each field it checks. Minimize its use and place it last in the validators array so cheaper validators (presence, numericality) fail first.
+  comment uniqueness LAST — DB query is the expensive one. endcomment
+  function c = 'modules/core/lib/validations/uniqueness',
+    c: c, field_name: 'email', object: object, table: 'user_profile'
 
-```liquid
-{% assign validators = [
-  { "name": "presence", "property": "email" },
-  { "name": "format", "property": "email", "options": { "pattern": "^[^@]+@[^@]+\\.[^@]+$" } },
-  { "name": "uniqueness", "property": "email", "options": { "table": "user_profile" } }
-] %}
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
 ## Handling File Uploads in Commands
 
-For commands that process file uploads, the file data comes through `context.params` as an upload object. Pass the relevant properties to your command.
+For commands that process file uploads, the file data comes through
+`context.params` as an upload object. Pass the relevant properties via
+`params`.
 
 ```liquid
-{% function result = 'lib/commands/documents/create',
-  title: context.params.document.title,
-  file: context.params.document.file
+{% function result = 'commands/documents/create',
+  params: { title: context.params.document.title, file: context.params.document.file }
 %}
 ```
 
-In the command, include the file property in the object and ensure the schema defines the field with type `upload`:
+In the build phase, normalize the file property; in the check phase,
+validate it like any other field. Schema must declare the field as
+type `upload`:
 
 ```yaml
 # app/schema/document.yml
@@ -142,51 +198,61 @@ properties:
 
 ## Idempotent Commands
 
-For operations that might be retried (e.g., background jobs with `max_attempts > 1`), design commands to be idempotent.
+For operations that might be retried (e.g. background jobs with
+`max_attempts > 1`), make commands idempotent by checking for existing
+records before creating.
 
 ```liquid
-{% comment %} Check if the record already exists before creating {% endcomment %}
-{% graphql existing = 'products/find_by_external_id', external_id: external_id %}
-
-{% if existing.records.results.size > 0 %}
-  {% assign object = existing.records.results.first %}
-  {% assign object = object | hash_merge: valid: true, errors: {} %}
-{% else %}
-  {% comment %} Standard build/check/execute {% endcomment %}
-  {% function object = 'modules/core/commands/build', object: object %}
-  {% function object = 'modules/core/commands/check', object: object, validators: validators %}
-  {% if object.valid %}
-    {% function object = 'modules/core/commands/execute',
-      mutation_name: 'products/create',
-      selection: 'record_create',
-      object: object
-    %}
-  {% endif %}
-{% endif %}
-{% return object %}
+{% comment %} app/lib/commands/products/import.liquid {% endcomment %}
+{% liquid
+  graphql existing = 'products/find_by_external_id', external_id: external_id
+
+  if existing.records.results.size > 0
+    assign object = existing.records.results | first
+    assign object = object | hash_merge: valid: true, errors: empty
+    return object
+  endif
+
+  function object = 'commands/products/create/build',
+    object: { external_id: external_id, title: title }
+  function object = 'commands/products/create/check', object: object
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
+    mutation_name: 'products/create',
+    selection: 'record_create',
+    object: object
+
+  return object
+%}
 ```
 
 ## Debugging Commands
 
-Use the `{% log %}` tag to inspect command state at each stage:
+Use `{% log %}` to inspect command state at each phase boundary.
 
 ```liquid
-{% function object = 'modules/core/commands/build', object: object %}
-{% log object, type: 'debug' %}
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  log object, type: 'debug'
 
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-{% log object, type: 'debug' %}
+  function object = 'commands/products/create/check', object: object
+  log object, type: 'debug'
+%}
 ```
 
-Monitor output with `pos-cli logs` to see the object state at each step.
+Monitor output with `pos-cli logs` to see the object state at each
+step.
 
 ## See Also
 
 - [README.md](README.md) -- Commands overview
 - [configuration.md](configuration.md) -- File layout and setup
-- [api.md](api.md) -- Core helper signatures
+- [api.md](api.md) -- Module-level command runner + validator family
 - [patterns.md](patterns.md) -- Standard patterns to build on
 - [gotchas.md](gotchas.md) -- Common errors and limits
+- [modules/core/advanced.md](../modules/core/advanced.md) -- Custom validators
 - [Background Jobs](../background-jobs/) -- Async execution details
 - [Events & Consumers](../events-consumers/) -- Event publishing from commands
-- [Caching](../caching/) -- Caching strategies around commands
diff --git a/src/data/references/commands/api.md b/src/data/references/commands/api.md
index a3ca339..e828386 100644
--- a/src/data/references/commands/api.md
+++ b/src/data/references/commands/api.md
@@ -1,145 +1,188 @@
 # Commands -- API Reference
 
-## Core Module Helpers
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The live
+> API surface is the source of truth — call
+> `module_info(name: 'core', section: 'api')`. This file gives narrative
+> notes on the command-runner shape and validator family.
 
-All command helpers are provided by `pos-module-core` and called via the `{% function %}` tag.
+## Module-Level: Only `modules/core/commands/execute`
 
-### `modules/core/commands/build`
-
-Initializes the command object, adding metadata fields (`valid`, `errors`).
-
-```liquid
-{% function object = 'modules/core/commands/build', object: object %}
-```
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `object` | Hash | Yes | The raw data hash built via `assign` with a hash literal |
-
-**Returns:** Hash with original fields plus `valid: true` and `errors: {}`.
-
-### `modules/core/commands/check`
-
-Validates the object against an array of validator definitions.
-
-```liquid
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-```
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `object` | Hash | Yes | Object from the build stage |
-| `validators` | Array | Yes | JSON array of validator hashes |
-
-**Returns:** Object with `valid` set to `false` and `errors` populated if any validation fails.
+There is **no** `modules/core/commands/build` and **no**
+`modules/core/commands/check`. The build and check phases are
+**app-level** files inside your own command directory — see
+[configuration.md](configuration.md) and [patterns.md](patterns.md).
+Calling `'modules/core/commands/build'` will fail with "partial not
+found" — see [gotchas.md](gotchas.md).
 
 ### `modules/core/commands/execute`
 
-Persists the object by running a GraphQL mutation.
+Runs a GraphQL mutation with the validated object as `args`.
 
 ```liquid
 {% function object = 'modules/core/commands/execute',
-  mutation_name: 'products/create',
-  selection: 'record_create',
-  object: object
-%}
+   mutation_name: 'products/create',
+   selection: 'record_create',
+   object: object %}
 ```
 
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `mutation_name` | String | Yes | Path to `.graphql` file (relative to `app/graphql/`) |
-| `selection` | String | Yes | Top-level field name in the mutation response (e.g., `record_create`) |
-| `object` | Hash | Yes | Validated object from the check stage |
+| Parameter       | Type   | Required | Description                                    |
+|-----------------|--------|----------|------------------------------------------------|
+| `mutation_name` | String | Yes      | Path to `.graphql` file (relative to `app/graphql/`) |
+| `selection`     | String | No       | Top-level field name in the mutation response (default `record`; record CRUD ops use `record_create` / `record_update` / `record_delete`) |
+| `object`        | Hash   | Yes      | Validated object passed as `args`              |
 
-**Returns:** Object with `id`, `created_at`, and other fields merged from the mutation response.
+**Returns:** the selected record from the mutation result, with
+`object.valid = true` set on success.
 
 ### `modules/core/commands/events/publish`
 
 Publishes an event after a successful command execution.
 
 ```liquid
-{% function _ = 'modules/core/commands/events/publish', type: 'product_created', object: object %}
-```
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `type` | String | Yes | Event type identifier (matches consumer directory name) |
-| `object` | Hash | Yes | Data payload available to consumers as `event.object` |
-
-**Returns:** Ignored (assign to `_`).
-
-## Validator Definitions
-
-Validators are defined as a JSON array of hashes. Each hash requires `name` and `property` at minimum.
-
-### `presence`
-
-Field must not be blank, null, or empty string.
-
-```json
-{ "name": "presence", "property": "title" }
+{% function _ = 'modules/core/commands/events/publish',
+   type: 'product_created', object: object %}
 ```
 
-### `numericality`
+| Parameter | Type   | Required | Description                                        |
+|-----------|--------|----------|----------------------------------------------------|
+| `type`    | String | Yes      | Event-type identifier (matches consumer directory) |
+| `object`  | Hash   | Yes      | Payload available to consumers as `event.object`   |
 
-Field must be a valid number.
+**Returns:** ignored — assign to `_`.
 
-```json
-{ "name": "numericality", "property": "price" }
-```
+### Other module commands
 
-### `uniqueness`
+| Command | Description |
+|---------|-------------|
+| `modules/core/commands/events/broadcast` | Fan-out to multiple type-prefixed consumers |
+| `modules/core/commands/session/get` | Read a session value |
+| `modules/core/commands/session/set` | Write a session value (with optional `from` for flash auto-clear) |
+| `modules/core/commands/session/clear` | Clear a session value |
 
-Field must be unique within the specified table.
+Use `module_info(name: 'core', section: 'api')` for the full live list.
 
-```json
-{ "name": "uniqueness", "property": "email", "options": { "table": "user_profile" } }
-```
+## App-Level: Build / Check Phases (your code)
 
-### `length`
+The build and check phases live in your own app, conventionally as
+sibling files of the orchestrator under
+`app/lib/commands///`. They have no signature
+prescribed by the module — they're regular Liquid partials with
+`{% doc %}` `@param` declarations.
 
-Field string length must fall within constraints.
+### Build phase signature
 
-```json
-{ "name": "length", "property": "title", "options": { "minimum": 3, "maximum": 255 } }
+```liquid
+{% comment %} app/lib/commands/products/create/build.liquid {% endcomment %}
+{% doc %}
+  @param {object} object - raw input from the orchestrator
+  @param {object} existing - optional, used by update commands
+{% enddoc %}
+{% liquid
+  assign object = object | hash_merge: valid: true, errors: empty
+  return object
+%}
 ```
 
-### `format`
+The build phase normalizes input, merges defaults, and seeds the
+contract `errors` so the check phase can append to it.
 
-Field must match a regular expression.
+### Check phase signature
 
-```json
-{ "name": "format", "property": "slug", "options": { "pattern": "^[a-z0-9-]+$" } }
+```liquid
+{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %}
+{% doc %}
+  @param {object} object - object from the build phase
+{% enddoc %}
+{% liquid
+  assign c = object.errors | default: empty
+
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'title', object: object
+  function c = 'modules/core/lib/validations/number',
+    c: c, field_name: 'price', object: object, gt: 0
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
-### `inclusion`
-
-Field value must be in a predefined list.
+The check phase chains validator calls, threading the contract `c`
+through each. At the end it sets `object.errors` and `object.valid`.
+
+## Validator Family
+
+All validators live at `modules/core/lib/validations/` (note the
+`lib/` segment — `modules/core/validations/` does not exist).
+They take `c` (contract / errors hash), `field_name`, `object`, and
+validator-specific options. They APPEND to `c` and RETURN it; chain
+them by passing the result back as the next call's `c`.
+
+| Validator                | Options (modern names)                                  | Notes |
+|--------------------------|---------------------------------------------------------|-------|
+| `presence`               | `allow_blank`, `message`                                | Falsey-blank fails |
+| `length`                 | `min`, `max`, `eq`                                      | String length |
+| `number`                 | `gt`, `gte`, `lt`, `lte`, `eq`, `ne`                    | Replaces legacy `numericality` (with `greater_than`/`less_than`) |
+| `date`                   | `format`, `before`, `after`                             | |
+| `email`                  | (none)                                                  | |
+| `is_url`                 | (none)                                                  | |
+| `matches`                | `regexp`, `allow_blank`                                 | Replaces legacy `format` (with param `pattern`) |
+| `equal`                  | `to`                                                    | Replaces legacy `confirmation` — set `to: 'password_confirmation'` for the pwd-match case |
+| `included`               | `in`                                                    | Replaces legacy `inclusion.values` |
+| `elements_included`      | `in`                                                    | Same as `included` but on array fields |
+| `unique_elements`        | (none)                                                  | Array elements must be unique |
+| `each_element_length`    | `min`, `max`                                            | |
+| `uniqueness`             | `table`, `scope`                                        | DB query — keep last in the chain so cheaper validators short-circuit |
+| `password_complexity`    | `min_length`, `require_digit`, `require_special`, ...   | |
+| `hcaptcha`               | (none)                                                  | hCaptcha verification |
+| `truthy`                 | (none)                                                  | Field must be truthy |
+| `not_null`               | (none)                                                  | Field must not be `nil` |
+| `exist_in_db`            | `table`, `field`                                        | Foreign-key existence |
+| `valid_object`           | `validators`                                            | Recursive sub-object validation |
+
+### Calling pattern (canonical)
 
-```json
-{ "name": "inclusion", "property": "status", "options": { "values": ["draft", "published", "archived"] } }
-```
-
-### `confirmation`
+```liquid
+{% function c = 'modules/core/lib/validations/presence',
+   c: object.errors, field_name: 'title', object: object %}
 
-Two fields must match (e.g., password and password confirmation).
+{% function c = 'modules/core/lib/validations/number',
+   c: c, field_name: 'price', object: object, gt: 0 %}
 
-```json
-{ "name": "confirmation", "property": "password" }
+{% function c = 'modules/core/lib/validations/matches',
+   c: c, field_name: 'sku', object: object,
+   regexp: '^[A-Z]{2,4}-[0-9]{4}$', allow_blank: true %}
 ```
 
-This expects a corresponding `password_confirmation` field in the object.
+Argument order: `c, field_name, object, [options...]` — matches the
+`@param` order in each validator file. See
+[modules/core/api.md](../modules/core/api.md) for the full validator
+reference and option semantics.
+
+## Legacy Forms — No Longer Supported
+
+The following forms appear in older docs and code; they will fail at
+function-resolve time on pos-cli 6.0.7+:
+
+- `'modules/core/commands/build'` — does not exist (the build phase is
+  app-level; see above).
+- `'modules/core/commands/check'` — does not exist; same reason.
+- `'modules/core/validations/'` — wrong path; the validators
+  live at `modules/core/lib/validations/`.
+- `validators` array passed to a single check helper —
+  `validators: [{ name: 'presence', property: 'X' }, ...]` was the
+  legacy shape that's no longer supported. Modern code chains
+  individual validator calls (see calling pattern above).
+- `numericality` validator — replaced by `number`.
+- `format` validator — replaced by `matches` (option `pattern` →
+  `regexp`).
+- `confirmation` validator — replaced by `equal` with explicit `to:`.
+- `inclusion` validator — replaced by `included` with `in:`.
 
 ## Result Object Structure
 
+After a successful execute:
+
 ```json
 {
   "title": "Widget",
@@ -151,7 +194,7 @@ This expects a corresponding `password_confirmation` field in the object.
 }
 ```
 
-On validation failure:
+After validation failure:
 
 ```json
 {
@@ -159,27 +202,32 @@ On validation failure:
   "price": null,
   "valid": false,
   "errors": {
-    "title": ["app.errors.blank"],
-    "price": ["app.errors.blank", "app.errors.not_a_number"]
+    "title": ["modules/core/validation.blank"],
+    "price": ["modules/core/validation.blank", "modules/core/validation.number"]
   }
 }
 ```
 
-## Calling a Command
+Error values are translation KEYS — translate at the display layer with
+`| t`.
 
-From a page or another partial:
+## Calling a Command from a Page
 
 ```liquid
-{% function result = 'lib/commands/products/create', title: "Widget", price: 19.99 %}
+{% function result = 'commands/products/create',
+   params: context.params.product %}
 ```
 
-Parameters are passed as named arguments and become local variables inside the command file.
+Parameters are passed as named arguments and become local variables
+inside the orchestrator file.
 
 ## See Also
 
 - [README.md](README.md) -- Commands overview
 - [configuration.md](configuration.md) -- File layout and naming
 - [patterns.md](patterns.md) -- Real-world usage examples
-- [gotchas.md](gotchas.md) -- Common API misuse and error messages
-- [advanced.md](advanced.md) -- Advanced validator combinations and custom validators
+- [gotchas.md](gotchas.md) -- Common API misuse
+- [advanced.md](advanced.md) -- Nested commands, transactions, background jobs
+- [modules/core/api.md](../modules/core/api.md) -- Authoritative validator
+  reference (this file mirrors it for the commands domain).
 - [Liquid Tags](../liquid/tags/) -- `function`, `assign`, and other tag references
diff --git a/src/data/references/commands/configuration.md b/src/data/references/commands/configuration.md
index 0e3c7eb..9921026 100644
--- a/src/data/references/commands/configuration.md
+++ b/src/data/references/commands/configuration.md
@@ -1,53 +1,79 @@
 # Commands -- Configuration Reference
 
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax).
+
 ## Directory Structure
 
-Commands live under `app/lib/commands/`. Organize by resource name, then action:
+Commands live under `app/lib/commands/`. Each action is **three** files:
+the orchestrator and a sibling directory holding `build.liquid` and
+`check.liquid`.
 
 ```
 app/
 ├── lib/
 │   └── commands/
 │       ├── products/
-│       │   ├── create.liquid
+│       │   ├── create.liquid              # orchestrator
+│       │   ├── create/
+│       │   │   ├── build.liquid           # build phase
+│       │   │   └── check.liquid           # check phase
 │       │   ├── update.liquid
-│       │   └── delete.liquid
+│       │   ├── update/
+│       │   │   ├── build.liquid
+│       │   │   └── check.liquid
+│       │   └── delete.liquid              # delete typically skips build/check
 │       ├── orders/
 │       │   ├── create.liquid
-│       │   ├── update.liquid
+│       │   ├── create/
+│       │   │   ├── build.liquid
+│       │   │   └── check.liquid
 │       │   ├── cancel.liquid
 │       │   └── fulfill.liquid
 │       └── users/
 │           ├── create.liquid
-│           └── update_profile.liquid
+│           └── create/
+│               ├── build.liquid
+│               └── check.liquid
 ├── graphql/
 │   ├── products/
-│   │   ├── create.graphql      # mutation used by commands/products/create
+│   │   ├── create.graphql
 │   │   ├── update.graphql
 │   │   └── delete.graphql
 │   └── orders/
 │       ├── create.graphql
 │       └── update.graphql
 └── schema/
-    ├── product.yml              # table definition
+    ├── product.yml
     └── order.yml
 ```
 
+The build/check phases for each action are **inline phases of your
+command** — there is **no** module-level `commands/build` or
+`commands/check`. Only `modules/core/commands/execute` runs at the
+module top level.
+
 ## Naming Conventions
 
 | Element | Convention | Example |
 |---------|-----------|---------|
-| Command file | `app/lib/commands//.liquid` | `app/lib/commands/products/create.liquid` |
+| Orchestrator | `app/lib/commands//.liquid` | `app/lib/commands/products/create.liquid` |
+| Build phase | `app/lib/commands///build.liquid` | `app/lib/commands/products/create/build.liquid` |
+| Check phase | `app/lib/commands///check.liquid` | `app/lib/commands/products/create/check.liquid` |
 | GraphQL mutation | `app/graphql//.graphql` | `app/graphql/products/create.graphql` |
 | Schema table | `app/schema/.yml` | `app/schema/product.yml` |
-| Command call | `lib/commands//` | `lib/commands/products/create` |
+| Command call | `commands//` | `commands/products/create` |
+| Phase call (from orchestrator) | `commands///` | `commands/products/create/build` |
 | Mutation name | `/` | `products/create` |
 
-Note: When calling a command, use `lib/commands/...` — the `lib/` prefix maps to `app/lib/`.
+Note: When calling a command, use `commands/...` (NOT `lib/commands/...`).
+The platformOS partial resolver searches `app/lib/` automatically —
+adding a `lib/` prefix produces an invalid path like
+`app/lib/lib/commands/...`.
 
 ## Required GraphQL Mutation
 
-Each command that persists data requires a corresponding `.graphql` mutation file. Example for `products/create`:
+Each command that persists data requires a corresponding `.graphql`
+mutation file. Example for `products/create`:
 
 ```graphql
 # app/graphql/products/create.graphql
@@ -72,7 +98,7 @@ mutation products_create($object: HashObject!) {
 
 ## Required Schema Table
 
-Commands typically operate on tables defined in `app/schema/`. Example:
+Commands typically operate on tables defined in `app/schema/`:
 
 ```yaml
 # app/schema/product.yml
@@ -86,49 +112,97 @@ properties:
     type: text
 ```
 
-## Command File Template
+## Command File Templates
 
-Every command file follows this skeleton:
+### Orchestrator template
 
 ```liquid
 {% comment %} app/lib/commands/products/create.liquid {% endcomment %}
-
-{% comment %} === BUILD === {% endcomment %}
-{% assign object = { "title": title, "price": price } %}
-{% function object = 'modules/core/commands/build', object: object %}
-
-{% comment %} === CHECK === {% endcomment %}
-{% assign validators = [
-  { "name": "presence", "property": "title" },
-  { "name": "numericality", "property": "price" }
-] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-
-{% comment %} === EXECUTE === {% endcomment %}
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
+{% doc %}
+  @param {object} params - raw input (typically context.params.)
+{% enddoc %}
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  function object = 'commands/products/create/check', object: object
+
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
     mutation_name: 'products/create',
     selection: 'record_create',
     object: object
-  %}
-{% endif %}
 
-{% return object %}
+  return object
+%}
+```
+
+### Build phase template
+
+```liquid
+{% comment %} app/lib/commands/products/create/build.liquid {% endcomment %}
+{% doc %}
+  @param {object} object - raw input from the orchestrator
+{% enddoc %}
+{% liquid
+  assign object = object | hash_merge: valid: true, errors: empty
+  return object
+%}
+```
+
+### Check phase template
+
+```liquid
+{% comment %} app/lib/commands/products/create/check.liquid {% endcomment %}
+{% doc %}
+  @param {object} object - object from the build phase
+{% enddoc %}
+{% liquid
+  assign c = object.errors | default: empty
+
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'title', object: object
+  function c = 'modules/core/lib/validations/number',
+    c: c, field_name: 'price', object: object, gt: 0
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
 ## Module Dependency
 
-Commands require `pos-module-core`. Ensure it is installed:
+Commands require `pos-module-core` for `commands/execute` and the
+validator family. Ensure it's installed:
 
 ```bash
 pos-cli modules install core
 ```
 
-The core module provides the `build`, `check`, and `execute` helpers. Without it, the `modules/core/commands/*` partials will not resolve.
+Without it, every `modules/core/...` partial reference will fail to
+resolve. Note: installing core does **not** make
+`modules/core/commands/build` or `modules/core/commands/check` exist —
+those phases are app-level files you write yourself.
+
+## Scaffolding
+
+Run the CRUD generator to create the canonical layout in one command:
+
+```bash
+pos-cli generators run crud --resource product --include-views
+```
+
+This produces the orchestrator + build/check siblings + GraphQL
+mutation + schema entry + view partials in one shot, all wired with
+the canonical syntax.
 
 ## Configuration Checklist
 
-- [ ] Command file at `app/lib/commands//.liquid`
+- [ ] Orchestrator at `app/lib/commands//.liquid`
+- [ ] Build phase at `app/lib/commands///build.liquid`
+- [ ] Check phase at `app/lib/commands///check.liquid`
 - [ ] GraphQL mutation at `app/graphql//.graphql`
 - [ ] Schema table at `app/schema/.yml`
 - [ ] `pos-module-core` installed
@@ -137,7 +211,7 @@ The core module provides the `build`, `check`, and `execute` helpers. Without it
 ## See Also
 
 - [README.md](README.md) -- Commands overview and getting started
-- [api.md](api.md) -- Core module helper signatures and validator details
+- [api.md](api.md) -- Module-level command runner + validator family
 - [patterns.md](patterns.md) -- Real-world command examples
 - [gotchas.md](gotchas.md) -- Common configuration mistakes
 - [advanced.md](advanced.md) -- Multi-step commands and advanced configuration
diff --git a/src/data/references/commands/gotchas.md b/src/data/references/commands/gotchas.md
index 17f7ae1..0760ccc 100644
--- a/src/data/references/commands/gotchas.md
+++ b/src/data/references/commands/gotchas.md
@@ -1,24 +1,153 @@
 # Commands -- Gotchas and Troubleshooting
 
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The most
+> common cause of mysterious "partial not found" errors is calling a
+> phantom `modules/core/commands/build` or `…/check` — see TOP GOTCHA below.
+
+## TOP GOTCHA: `modules/core/commands/build` and `…/check` DO NOT EXIST
+
+There is **no** `modules/core/commands/build.liquid` and **no**
+`modules/core/commands/check.liquid`. The build/check phases are
+**app-level** files inside your own command directory, e.g.
+`app/lib/commands/products/create/build.liquid` and
+`app/lib/commands/products/create/check.liquid`.
+
+```liquid
+{% comment %} ✗ FAILS — no such file in core 2.1.8+ {% endcomment %}
+{% function object = 'modules/core/commands/build', object: params %}
+{% function object = 'modules/core/commands/check',
+   object: object, validators: validators %}
+
+{% comment %} ✓ Correct — your own phase partials {% endcomment %}
+{% function object = 'commands/products/create/build', object: params %}
+{% function object = 'commands/products/create/check', object: object %}
+```
+
+Only `modules/core/commands/execute` runs at the module top level.
+Generate the orchestrator + build + check trio with:
+
+```bash
+pos-cli generators run crud --resource  --include-views
+```
+
 ## Common Errors
 
 ### "Template not found: modules/core/commands/build"
 
+**Cause:** You're calling the phantom module-level build/check helpers
+(see TOP GOTCHA). They don't exist regardless of whether the core
+module is installed.
+
+**Solution:** Replace with calls to your app's phase partials. The
+build phase normalizes input; the check phase chains validator calls.
+See [patterns.md](patterns.md) for the canonical layout.
+
+### "Template not found: modules/core/validations/"
+
+**Cause:** Wrong path. The validators live at
+`modules/core/lib/validations/` — note the `lib/` segment.
+
+**Solution:** Use the canonical path:
+
+```liquid
+{% function c = 'modules/core/lib/validations/presence',
+   c: c, field_name: 'title', object: object %}
+```
+
+### "Template not found: modules/core/"
+
 **Cause:** The `pos-module-core` module is not installed or not synced.
 
 **Solution:** Run `pos-cli modules install core` and deploy or sync.
 
+### "Validators don't fire" / `object.errors` always empty
+
+**Cause:** The check phase isn't threading the contract `c` through
+each validator call. Each validator returns the contract; you must
+pass that result back as the next call's `c:` argument. At the end,
+set `object.errors = c` and `object.valid = c == empty`.
+
+**Solution:**
+
+```liquid
+{% liquid
+  assign c = object.errors | default: empty
+
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'title', object: object
+  function c = 'modules/core/lib/validations/length',
+    c: c, field_name: 'title', object: object, min: 3
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
+```
+
+### "Validator argument order seems wrong"
+
+**Cause:** The argument order for every validator is
+`c, field_name, object, [options...]` — matching the validator file's
+`@param` order. Any other order may pass arguments to the wrong
+parameter.
+
+**Solution:** Always:
+
+```liquid
+{% function c = 'modules/core/lib/validations/',
+   c: c, field_name: '', object: object,  %}
+```
+
+### "Legacy validator names fail at function-resolve"
+
+**Cause:** Older docs and code use names that were renamed in pos-cli
+6.0.7+:
+
+| Legacy            | Modern replacement                  |
+|-------------------|-------------------------------------|
+| `numericality`    | `number` (options `gt`/`gte`/`lt`/`lte`/`eq`/`ne`) |
+| `format`          | `matches` (option `regexp`)         |
+| `confirmation`    | `equal` with `to: ''`  |
+| `inclusion`       | `included` with `in: [...]`         |
+
+**Solution:** Replace the validator name and options. The legacy names
+are no longer aliased.
+
+### "`validators: validators` array shape no longer works"
+
+**Cause:** The legacy shape passed a JSON array of validator hashes to
+a single check helper:
+
+```liquid
+{% comment %} ✗ Legacy — no longer supported {% endcomment %}
+{% assign validators = [
+  { "name": "presence", "property": "title" },
+  { "name": "numericality", "property": "price" }
+] %}
+{% function object = 'modules/core/commands/check',
+   object: object, validators: validators %}
+```
+
+**Solution:** Modern code chains individual validator calls — see
+[patterns.md](patterns.md) for the canonical shape.
+
 ### "Liquid error: undefined variable 'object'"
 
-**Cause:** The variable name in the `assign` tag does not match what is passed to `build`. Or the `{% function %}` assignment was skipped.
+**Cause:** The variable name in the `assign` tag doesn't match what
+the orchestrator passes. Or the build call's assignment was skipped.
 
-**Solution:** Ensure `assign` creates a variable called `object` and the build call uses `object: object`.
+**Solution:** Ensure your orchestrator passes a `params` (or whatever
+name) and your build phase declares it via `{% doc %}` `@param`. The
+build phase typically returns an `object` for the check phase to
+consume.
 
 ### "app.errors.blank" on a field that has a value
 
-**Cause:** The value was not properly referenced in the hash literal. Using a quoted string literal instead of a variable reference means the actual variable value is not included.
+**Cause:** Value not properly referenced in the hash literal — using a
+quoted string literal instead of a variable reference means the actual
+variable value isn't passed in.
 
-**Solution:** Use `assign` with hash literals and reference variables directly (without quotes). The deprecated `parse_json` tag required `{{ variable | json }}` for safe interpolation, but modern hash literals take variable names directly.
+**Solution:** Hash literals take variable names directly, no quotes:
 
 ```liquid
 {% comment %} WRONG -- string literal instead of variable reference {% endcomment %}
@@ -30,38 +159,65 @@
 
 ### "record_create returned nil" or empty result after execute
 
-**Cause:** The `selection` parameter does not match the top-level field in the GraphQL mutation response.
+**Cause:** The `selection` parameter doesn't match the top-level field
+in the GraphQL mutation response.
 
-**Solution:** If your mutation uses `record_create(...)`, the selection must be `'record_create'`. If it uses `record_update(...)`, use `'record_update'`. Check the `.graphql` file.
+**Solution:** Match the mutation's top-level alias literally. CRUD
+ops typically use `'record_create'`, `'record_update'`,
+`'record_delete'`. Inspect the `.graphql` file to confirm.
 
 ### "Validation passed but record was not created"
 
-**Cause:** The `{% if object.valid %}` guard around the execute stage is missing.
+**Cause:** Missing `{% if object.valid %}` guard around the execute
+call, or missing `if object.valid == false / return object` short-
+circuit before `execute`.
+
+**Solution:** Always guard the execute call:
+
+```liquid
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  function object = 'commands/products/create/check', object: object
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
+    mutation_name: 'products/create',
+    selection: 'record_create',
+    object: object
 
-**Solution:** Always wrap the execute call in an `{% if object.valid %}` block. Without it, the execute call may silently fail or never run.
+  return object
+%}
+```
 
 ### "Cannot read property 'valid' of null"
 
-**Cause:** The command file does not include `{% return object %}` at the end, so the caller receives `nil`.
+**Cause:** Command file doesn't include `{% return object %}` at the
+end, so the caller receives `nil`.
 
-**Solution:** Every command must end with `{% return object %}`.
+**Solution:** Every command (orchestrator, build, check) must end with
+`{% return  %}`.
 
 ### "Mutation variable $object is not defined"
 
-**Cause:** The GraphQL mutation file expects `$object` but the execute helper is not passing it correctly, or the mutation signature is wrong.
+**Cause:** GraphQL mutation file expects `$object` but the execute
+helper isn't passing it correctly, or the mutation signature is wrong.
 
-**Solution:** Ensure the mutation declares `mutation name($object: HashObject!)` and references `$object.field_name` in property values.
+**Solution:** Ensure the mutation declares
+`mutation name($object: HashObject!)` and references `$object.field_name`
+in property values.
 
 ## Limits
 
 | Limit | Value | Notes |
 |-------|-------|-------|
-| Validators per check call | No hard limit | Keep reasonable for performance (under 50) |
-| Nested command depth | No hard limit | Avoid deep nesting; prefer events for decoupling |
-| Object properties | No hard limit | Properties must match schema table fields for persistence |
+| Validators per check phase | No hard limit | Performance degrades beyond ~20 |
+| Nested command depth | ~3 levels | Prefer events for decoupling beyond that |
+| Object properties | No hard limit | Properties must match schema fields for persistence |
 | Background job max_attempts | 1-5 | Commands run as background jobs inherit this limit |
-| GraphQL mutation timeout | Platform default | Long-running mutations may time out |
-| Uniqueness validator | Requires table option | Queries the database; slower than other validators |
+| GraphQL mutation timeout | Platform default | Long mutations may time out |
+| Uniqueness validator | Requires `table:` option | DB query — slower than other validators; place last in chain |
 
 ## Troubleshooting Flowchart
 
@@ -69,22 +225,26 @@
 Command returns unexpected result
 ├── result is nil
 │   └── Missing {% return object %} at end of command
+├── "Template not found: modules/core/commands/build" or "…/check"
+│   └── Phantom helpers — replace with your app's phase partials
+├── "Template not found: modules/core/validations/"
+│   └── Wrong path — use modules/core/lib/validations/
 ├── result.valid is false unexpectedly
-│   ├── Check result.errors for field names and messages
+│   ├── Check result.errors for field names and translation keys
 │   ├── Is value present but errors say "blank"?
-│   │   └── Used string literal instead of variable reference in assign
+│   │   └── String literal instead of variable reference in hash literal
 │   ├── Is uniqueness failing?
-│   │   └── Check table option matches schema table name
-│   └── Is format failing?
-│       └── Verify regex pattern in validator options
+│   │   └── Check `table:` option matches schema table name
+│   └── Is matches failing?
+│       └── Verify regexp, and remember it's `regexp:` not `pattern:`
 ├── result.valid is true but no record created
-│   ├── Missing {% if object.valid %} guard around execute
+│   ├── Missing `if object.valid == false / return object` guard
 │   ├── Wrong mutation_name (file not found)
 │   └── Wrong selection (does not match mutation response field)
 ├── result has no id after execute
 │   ├── Mutation .graphql file missing id in selection set
 │   └── selection parameter mismatch
-└── "Template not found" error
+└── "Template not found" (other)
     ├── pos-module-core not installed
     ├── Command path typo in {% function %} call
     └── File in wrong directory (must be app/lib/commands/)
@@ -94,6 +254,8 @@ Command returns unexpected result
 
 - [README.md](README.md) -- Commands overview
 - [configuration.md](configuration.md) -- Correct file layout
-- [api.md](api.md) -- Helper signatures and validator details
+- [api.md](api.md) -- Module-level runner + validator family
 - [patterns.md](patterns.md) -- Working examples to compare against
 - [advanced.md](advanced.md) -- Edge cases and advanced troubleshooting
+- [modules/core/gotchas.md](../modules/core/gotchas.md) -- Authoritative
+  source for the phantom build/check error and validator renames.
diff --git a/src/data/references/commands/patterns.md b/src/data/references/commands/patterns.md
index 1a88eee..a1270c5 100644
--- a/src/data/references/commands/patterns.md
+++ b/src/data/references/commands/patterns.md
@@ -1,33 +1,95 @@
 # Commands -- Common Patterns
 
-## Pattern: Basic CRUD Command
+> Compatible with pos-cli 6.0.7+ (modernized canonical syntax). The
+> build/check phases live in your APP commands, not in
+> `modules/core/commands/`. Only `modules/core/commands/execute` runs at the
+> module top level. See [modules/core/patterns.md](../modules/core/patterns.md)
+> for the authoritative module-level pattern.
 
-The most common pattern is a create command called from a POST page.
+## Pattern: Basic CRUD Command (canonical)
 
-### Command file
+A command is **three** files per action: an orchestrator and two phase
+files (`build`, `check`) under a sibling directory. The orchestrator
+calls them in order, then invokes `modules/core/commands/execute` for
+the GraphQL mutation. There is **no** `modules/core/commands/build` or
+`modules/core/commands/check` — those phases are app-level.
 
-```liquid
-{% comment %} app/lib/commands/products/create.liquid {% endcomment %}
+```
+app/lib/commands/products/
+├── create.liquid              # orchestrator
+├── create/
+│   ├── build.liquid           # your build phase
+│   └── check.liquid           # your check phase
+├── update.liquid
+├── update/
+│   ├── build.liquid
+│   └── check.liquid
+└── delete.liquid              # delete typically skips build/check
+```
+
+### Orchestrator (`app/lib/commands/products/create.liquid`)
 
-{% assign object = { "title": title, "price": price, "description": description, "user_id": user_id } %}
-{% function object = 'modules/core/commands/build', object: object %}
+```liquid
+{% doc %}
+  @param {object} params - raw input (typically context.params.product)
+{% enddoc %}
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  function object = 'commands/products/create/check', object: object
 
-{% assign validators = [
-  { "name": "presence", "property": "title" },
-  { "name": "presence", "property": "price" },
-  { "name": "numericality", "property": "price" },
-  { "name": "length", "property": "title", "options": { "minimum": 3, "maximum": 255 } }
-] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
+  if object.valid == false
+    return object
+  endif
 
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
+  function object = 'modules/core/commands/execute',
     mutation_name: 'products/create',
     selection: 'record_create',
     object: object
-  %}
-{% endif %}
-{% return object %}
+
+  return object
+%}
+```
+
+### Build phase (`app/lib/commands/products/create/build.liquid`)
+
+The build phase normalizes input and seeds the validation contract.
+
+```liquid
+{% doc %}
+  @param {object} object - raw input from the orchestrator
+{% enddoc %}
+{% liquid
+  assign object = object | hash_merge: valid: true, errors: empty
+  return object
+%}
+```
+
+### Check phase (`app/lib/commands/products/create/check.liquid`)
+
+The check phase chains validators directly. Each call to a validator
+returns the contract `c`; thread it through every call. At the end set
+`object.errors` and `object.valid`.
+
+```liquid
+{% doc %}
+  @param {object} object - object built by the build phase
+{% enddoc %}
+{% liquid
+  assign c = object.errors | default: empty
+
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'title', object: object
+
+  function c = 'modules/core/lib/validations/length',
+    c: c, field_name: 'title', object: object, min: 3, max: 255
+
+  function c = 'modules/core/lib/validations/number',
+    c: c, field_name: 'price', object: object, gt: 0
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
 ### Page calling the command
@@ -39,17 +101,15 @@ slug: products
 method: post
 ---
 {% liquid
-  function profile = 'modules/user/queries/user/current'
-  include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'products.create'
+  graphql current_user = 'modules/user/queries/user/current'
+  function _ = 'modules/user/helpers/can_do_or_unauthorized',
+    requester: current_user, do: 'products.create'
 
-  function result = 'lib/commands/products/create',
-    title: context.params.product.title,
-    price: context.params.product.price,
-    description: context.params.product.description,
-    user_id: profile.id
+  function result = 'commands/products/create', params: context.params.product
 
   if result.valid
-    include 'modules/core/helpers/redirect_to', url: '/products', notice: 'app.products.created'
+    function _ = 'modules/core/helpers/redirect_to',
+      url: '/products', notice: 'app.products.created'
   else
     render 'products/form', product: result
   endif
@@ -58,99 +118,126 @@ method: post
 
 ## Pattern: Update Command
 
-Update commands fetch the existing record, merge changes, and persist.
+Update loads the existing record first, merges params on top, validates,
+executes.
 
 ```liquid
 {% comment %} app/lib/commands/products/update.liquid {% endcomment %}
+{% doc %}
+  @param {string} id     - record id
+  @param {object} params - raw input
+{% enddoc %}
+{% liquid
+  function existing = 'queries/products/find', id: id
+  if existing == blank
+    return { valid: false, errors: { base: ['Record not found'] } }
+  endif
 
-{% assign object = { "id": id, "title": title, "price": price } %}
-{% function object = 'modules/core/commands/build', object: object %}
+  assign params['id'] = id
+  function object = 'commands/products/update/build',
+    object: params, existing: existing
+  function object = 'commands/products/update/check', object: object
 
-{% assign validators = [
-  { "name": "presence", "property": "id" },
-  { "name": "presence", "property": "title" }
-] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
+  if object.valid == false
+    return object
+  endif
 
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
+  function object = 'modules/core/commands/execute',
     mutation_name: 'products/update',
     selection: 'record_update',
     object: object
-  %}
-{% endif %}
-{% return object %}
+
+  return object
+%}
 ```
 
 ## Pattern: Delete Command
 
-Delete commands typically only need an ID and authorization.
+Delete usually skips build/check (the page-level auth helper already
+gated it) and calls `execute` directly.
 
 ```liquid
 {% comment %} app/lib/commands/products/delete.liquid {% endcomment %}
+{% doc %}
+  @param {string} id - record id
+{% enddoc %}
+{% liquid
+  assign object = { id: id }
 
-{% assign object = { "id": id } %}
-{% function object = 'modules/core/commands/build', object: object %}
-
-{% assign validators = [{ "name": "presence", "property": "id" }] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
+  function object = 'modules/core/commands/execute',
     mutation_name: 'products/delete',
     selection: 'record_delete',
     object: object
-  %}
-{% endif %}
-{% return object %}
+
+  function _ = 'modules/core/commands/events/publish',
+    type: 'product_deleted', object: object
+
+  return object
+%}
 ```
 
 ## Pattern: Command with Event Publishing
 
-Publish an event after successful execution to trigger side effects.
+Publish an event AFTER `execute` succeeds to trigger side effects
+(notifications, audit logs, downstream consumers).
 
 ```liquid
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute',
+{% comment %} app/lib/commands/orders/create.liquid orchestrator {% endcomment %}
+{% liquid
+  function object = 'commands/orders/create/build', object: params
+  function object = 'commands/orders/create/check', object: object
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
     mutation_name: 'orders/create',
     selection: 'record_create',
     object: object
-  %}
 
-  {% function _ = 'modules/core/commands/events/publish',
-    type: 'order_created',
-    object: object
-  %}
-{% endif %}
-{% return object %}
+  function _ = 'modules/core/commands/events/publish',
+    type: 'order_created', object: object
+
+  return object
+%}
 ```
 
-## Pattern: Command with Conditional Validation
+## Pattern: Conditional Validation
 
-Add validators conditionally based on the data.
+Validators are called individually as `{% function %}` calls. To branch
+on a field value, simply place validator calls inside `if` blocks
+inside the check phase — no array config needed.
 
 ```liquid
-{% assign validators = [
-  { "name": "presence", "property": "email" },
-  { "name": "format", "property": "email", "options": { "pattern": "^[^@]+@[^@]+$" } }
-] %}
-
-{% if object.role == 'admin' %}
-  {% assign admin_validators = [{ "name": "presence", "property": "admin_code" }] %}
-  {% assign validators = validators | array_add: admin_validators %}
-{% endif %}
+{% comment %} app/lib/commands/users/create/check.liquid {% endcomment %}
+{% liquid
+  assign c = object.errors | default: empty
 
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
+  function c = 'modules/core/lib/validations/presence',
+    c: c, field_name: 'email', object: object
+  function c = 'modules/core/lib/validations/matches',
+    c: c, field_name: 'email', object: object,
+    regexp: '^[^@]+@[^@]+\.[^@]+$', allow_blank: true
+
+  if object.role == 'admin'
+    function c = 'modules/core/lib/validations/presence',
+      c: c, field_name: 'admin_code', object: object
+  endif
+
+  assign object.errors = c
+  assign object.valid  = c == empty
+  return object
+%}
 ```
 
 ## Pattern: Displaying Validation Errors
 
-Render errors in a form partial:
+Render errors in a form partial. The contract is a hash keyed by
+`field_name`; each value is an array of translation keys.
 
 ```liquid
 {% comment %} app/views/partials/products/form.liquid {% endcomment %}
-
-{% if product.errors.size > 0 %}
+{% if product.errors != empty %}
   
      
     
        
       {% for error in product.errors %}
@@ -172,40 +259,60 @@ Render errors in a form partial:
 
 ## Pattern: Calling One Command from Another
 
-Commands can compose by calling other commands internally.
+Commands compose by calling other orchestrators directly with
+`{% function %}`. Each composed command is a self-contained
+build → check → execute sequence.
 
 ```liquid
 {% comment %} app/lib/commands/orders/create_with_items.liquid {% endcomment %}
+{% doc %}
+  @param {string} user_id
+  @param {number} total
+  @param {array}  items
+{% enddoc %}
+{% liquid
+  function order = 'commands/orders/create',
+    params: { user_id: user_id, total: total }
+
+  if order.valid
+    for item in items
+      function line = 'commands/order_items/create',
+        params: { order_id: order.id, product_id: item.product_id, quantity: item.quantity }
+    endfor
+  endif
 
-{% function order = 'lib/commands/orders/create', user_id: user_id, total: total %}
-
-{% if order.valid %}
-  {% for item in items %}
-    {% function line = 'lib/commands/order_items/create',
-      order_id: order.id,
-      product_id: item.product_id,
-      quantity: item.quantity
-    %}
-  {% endfor %}
-{% endif %}
-
-{% return order %}
+  return order
+%}
 ```
 
 ## Best Practices
 
-1. **One responsibility per command** -- a command should do one thing (create a product, update an order).
-2. **Always return the object** -- callers rely on `result.valid` and `result.errors`.
-3. **Use hash literals with `assign`** -- build data objects using `{% assign object = { "key": variable } %}` rather than the deprecated `parse_json` tag.
-4. **Keep pages thin** -- pages call commands and handle routing; no business logic in pages.
-5. **Validate everything** -- never trust user input; always include a check stage.
+1. **One responsibility per command** — a command does one thing
+   (create a product, update an order).
+2. **Always return the object** — callers rely on `result.valid` and
+   `result.errors`.
+3. **Three files per command** — orchestrator + `/build.liquid` +
+   `/check.liquid`. Run `pos-cli generators run crud
+   --resource  --include-views` to scaffold the canonical layout.
+4. **Use hash literals with `assign`** — build data objects via
+   `{% assign object = { "key": variable } %}` rather than the deprecated
+   `parse_json` tag.
+5. **Keep pages thin** — pages call commands and handle routing; no
+   business logic in pages.
+6. **Validate everything** — never trust user input; always include a
+   check phase. Each validator call returns the contract — thread it
+   through.
+7. **Use canonical validator paths** — always
+   `modules/core/lib/validations/` (note the `lib/`). The path
+   `modules/core/validations/` does not exist.
 
 ## See Also
 
 - [README.md](README.md) -- Commands overview
 - [configuration.md](configuration.md) -- File layout and setup
-- [api.md](api.md) -- Helper signatures and validator reference
-- [gotchas.md](gotchas.md) -- Common mistakes and troubleshooting
-- [advanced.md](advanced.md) -- Advanced patterns and optimization
-- [Events & Consumers](../events-consumers/) -- Handling events published by commands
+- [api.md](api.md) -- Validator family + option names
+- [gotchas.md](gotchas.md) -- Common mistakes (esp. phantom build/check)
+- [advanced.md](advanced.md) -- Nested commands, background jobs, transactions
+- [modules/core/patterns.md](../modules/core/patterns.md) -- Authoritative
+  module-level pattern (this file mirrors it for the commands domain).
 - [Forms Reference](../forms/) -- Building forms that submit to commands
diff --git a/src/data/references/forms/README.md b/src/data/references/forms/README.md
index 00ba9b0..d80deb7 100644
--- a/src/data/references/forms/README.md
+++ b/src/data/references/forms/README.md
@@ -107,7 +107,7 @@ slug: api/products
 method: post
 ---
 {% liquid
-  function result = 'lib/commands/products/create',
+  function result = 'commands/products/create',
     title: context.params.product.title,
     price: context.params.product.price
 
diff --git a/src/data/references/graphql/gotchas.md b/src/data/references/graphql/gotchas.md
index 2869460..6aaab60 100644
--- a/src/data/references/graphql/gotchas.md
+++ b/src/data/references/graphql/gotchas.md
@@ -121,7 +121,7 @@ query GetProducts {
 Access in Liquid:
 
 ```liquid
-{% graphql g = 'lib/queries/products/list' %}
+{% graphql g = 'products/list' %}
 {% for product in g.records.results %}
   {{ product.properties_object.title }}
   {{ product.properties_object.price | property_float }}
@@ -137,7 +137,7 @@ Use `property_float` / `property_int` / `property_boolean` accessors when you ne
 the GraphQL query exactly — the top-level key is the query field name, not `results` or `data`.
 
 ```liquid
-{% graphql g = 'lib/queries/records/list' %}
+{% graphql g = 'records/list' %}
 
 {# WRONG — data is not at the root: #}
 {% for item in g.results %}
diff --git a/src/data/references/liquid/tags/gotchas.md b/src/data/references/liquid/tags/gotchas.md
index 173f7a4..4e1e28c 100644
--- a/src/data/references/liquid/tags/gotchas.md
+++ b/src/data/references/liquid/tags/gotchas.md
@@ -19,12 +19,12 @@ is outdated and does not work in pos-cli v6.0.0+.
 {% endgraphql %}
 
 {# RIGHT — file-reference syntax only: #}
-{% graphql get_user = 'lib/queries/users/find', id: context.params.id %}
+{% graphql get_user = 'users/find', id: context.params.id %}
 {{ get_user.user.email }}
 ```
 
 The path is relative to `app/graphql/`. The file must exist at
-`app/graphql/lib/queries/users/find.graphql`.
+`app/graphql/users/find.graphql`.
 
 ---
 
@@ -36,14 +36,14 @@ pure rendering components — they receive data and display it.
 ```liquid
 {# WRONG — graphql inside a partial: #}
 {% comment %}@prompt: Shows the latest products{% endcomment %}
-{% graphql g = 'lib/queries/products/list' %}
+{% graphql g = 'products/list' %}
 {% for p in g.records.results %}
   {{ p.properties_object.title }}
 {% endfor %}
 
 {# RIGHT — page fetches, partial renders: #}
 {# In the page file: #}
-{% graphql g = 'lib/queries/products/list' %}
+{% graphql g = 'products/list' %}
 {% render 'products/list', products: g.records.results %}
 ```
 
@@ -71,7 +71,7 @@ inline syntax.
 {% endfunction %}
 
 {# RIGHT — function calls a partial file: #}
-{% function total = 'lib/helpers/calculate_total', price: product.price, qty: qty %}
+{% function total = 'helpers/calculate_total', price: product.price, qty: qty %}
 {{ total }}
 ```
 
diff --git a/src/data/references/liquid/tags/patterns.md b/src/data/references/liquid/tags/patterns.md
index a8d89e6..4c15807 100644
--- a/src/data/references/liquid/tags/patterns.md
+++ b/src/data/references/liquid/tags/patterns.md
@@ -38,7 +38,7 @@ Use `function` for partials that compute and return data. Use `render` for parti
 
 ```liquid
 {% liquid
-  function order = 'lib/commands/orders/create', user_id: profile.id, items: cart_items
+  function order = 'commands/orders/create', user_id: profile.id, items: cart_items
   if order.errors
     render 'orders/errors', errors: order.errors
     break
@@ -63,7 +63,7 @@ Offload slow operations (emails, API calls, heavy processing) to background jobs
 ### Background partial form (preferred for complex jobs)
 
 ```liquid
-{% background job = 'lib/jobs/process_payment', order_id: order.id, amount: total, delay: 0, priority: 'high' %}
+{% background job = 'jobs/process_payment', order_id: order.id, amount: total, delay: 0, priority: 'high' %}
 ```
 
 ## Transaction Pattern
diff --git a/src/data/references/liquid/variables/README.md b/src/data/references/liquid/variables/README.md
index 38f131f..4496f4a 100644
--- a/src/data/references/liquid/variables/README.md
+++ b/src/data/references/liquid/variables/README.md
@@ -74,12 +74,12 @@ Since variables are local, use these patterns:
 {% return result %}
 
 {% comment %} In calling page {% endcomment %}
-{% function data = 'lib/helpers/calculate', input: value %}
+{% function data = 'helpers/calculate', input: value %}
 {{ data }}
 ```
 
 ### Passing parameters (caller → partial)
 ```liquid
 {% render 'products/card', product: product, show_price: true %}
-{% function result = 'lib/commands/create', title: "Test" %}
+{% function result = 'commands/create', title: "Test" %}
 ```
diff --git a/src/data/references/modules/core/configuration.md b/src/data/references/modules/core/configuration.md
index 270ceec..f3ff73f 100644
--- a/src/data/references/modules/core/configuration.md
+++ b/src/data/references/modules/core/configuration.md
@@ -65,8 +65,9 @@ modules/core/
     views/                              # admin pages, layouts, partials
 ```
 
-There is NO `lib/commands/build.liquid` or `lib/commands/check.liquid` —
-those phases are app-level (or domain-specific within other commands).
+There is NO `commands/build.liquid` or `commands/check.liquid` exposed by
+core — those phases are inline files of YOUR command (siblings of your
+`execute.liquid` under `app/lib/commands//`).
 
 ## Overriding Module Files
 
diff --git a/src/data/references/pages/api.md b/src/data/references/pages/api.md
index 4f800e4..9afcf25 100644
--- a/src/data/references/pages/api.md
+++ b/src/data/references/pages/api.md
@@ -54,8 +54,8 @@ Calls a partial and captures its return value.
 
 ```liquid
 {% function profile = 'modules/user/queries/user/current' %}
-{% function valid = 'lib/commands/products/validate', params: context.params %}
-{% function slug = 'lib/helpers/slugify', text: product.title %}
+{% function valid = 'commands/products/validate', params: context.params %}
+{% function slug = 'helpers/slugify', text: product.title %}
 ```
 
 ### include
diff --git a/src/data/references/pages/gotchas.md b/src/data/references/pages/gotchas.md
index 224062d..71d7e84 100644
--- a/src/data/references/pages/gotchas.md
+++ b/src/data/references/pages/gotchas.md
@@ -16,7 +16,7 @@ but the architecture is wrong and becomes unmaintainable.
 slug: products/index
 layout: application
 ---
-{% graphql g = 'lib/queries/products/list' %}
+{% graphql g = 'products/list' %}
 
        
   
        Products
        
   {% for product in g.records.results %}
@@ -29,7 +29,7 @@ layout: application
 slug: products/index
 layout: application
 ---
-{% graphql g = 'lib/queries/products/list' %}
+{% graphql g = 'products/list' %}
 {% render 'products/index', products: g.records.results %}
 ```
 
@@ -61,7 +61,7 @@ metadata:
 
 ```liquid
 {# In page — after fetching data: #}
-{% graphql g = 'lib/queries/products/find', id: context.params.id %}
+{% graphql g = 'products/find', id: context.params.id %}
 {% assign product = g.record %}
 {% content_for 'title' %}{{ product.properties_object.name }}{% endcontent_for %}
 {% render 'products/show', product: product %}
diff --git a/src/data/references/pages/patterns.md b/src/data/references/pages/patterns.md
index 761be65..f0b4740 100644
--- a/src/data/references/pages/patterns.md
+++ b/src/data/references/pages/patterns.md
@@ -50,7 +50,7 @@ method: post
 {% liquid
   function profile = 'modules/user/queries/user/current'
   include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'products.create'
-  function result = 'lib/commands/products/create', params: context.params
+  function result = 'commands/products/create', params: context.params
   if result.errors != blank
     render 'products/new', errors: result.errors, params: context.params
     break
@@ -70,7 +70,7 @@ method: put
 {% liquid
   function profile = 'modules/user/queries/user/current'
   include 'modules/user/helpers/can_do_or_unauthorized', requester: profile, do: 'products.edit'
-  function result = 'lib/commands/products/update', id: context.params.id, params: context.params
+  function result = 'commands/products/update', id: context.params.id, params: context.params
   if result.errors != blank
     render 'products/edit', errors: result.errors, params: context.params, id: context.params.id
     break
diff --git a/src/data/references/partials/README.md b/src/data/references/partials/README.md
index a6e80f5..5c44a35 100644
--- a/src/data/references/partials/README.md
+++ b/src/data/references/partials/README.md
@@ -15,14 +15,14 @@ Partials contain all presentation HTML and reusable logic. They are the building
 
 ### As a function (returns data)
 ```liquid
-{% function result = 'lib/commands/products/create', title: "New Product", price: 19.99 %}
+{% function result = 'commands/products/create', title: "New Product", price: 19.99 %}
 ```
 
 ## Naming Rules
 
 - **NO underscore prefix** in filenames (e.g., `card.liquid`, NOT `_card.liquid`)
 - View partials: `render 'products/card'` → `app/views/partials/products/card.liquid`
-- Commands/queries: `function r = 'lib/commands/products/create'` → `app/lib/commands/products/create.liquid`
+- Commands/queries: `function r = 'commands/products/create'` → `app/lib/commands/products/create.liquid`
 
 ## Variable Scope
 
diff --git a/src/data/references/partials/advanced.md b/src/data/references/partials/advanced.md
index edd8763..150d18d 100644
--- a/src/data/references/partials/advanced.md
+++ b/src/data/references/partials/advanced.md
@@ -50,7 +50,7 @@ Use function partials to return configuration hashes:
 ```
 
 ```liquid
-{% function nav_items = 'lib/config/navigation' %}
+{% function nav_items = 'config/navigation' %}
 {% for item in nav_items %}
   {% assign label = item.label | t %}
   {% render 'shared/nav_link', label: label, url: item.url %}
@@ -93,7 +93,7 @@ Function partials (commands, helpers) are testable via pos-module-tests:
 
 ```liquid
 {% comment %} app/lib/tests/helpers/format_price_test.liquid {% endcomment %}
-{% function result = 'lib/helpers/format_price', amount: 19.99, currency: 'USD' %}
+{% function result = 'helpers/format_price', amount: 19.99, currency: 'USD' %}
 {% function contract = 'modules/tests/assertions/equal', contract: contract, given: result, expected: '$19.99' %}
 {% return contract %}
 ```
diff --git a/src/data/references/partials/configuration.md b/src/data/references/partials/configuration.md
index 3d7cdb9..3d445a8 100644
--- a/src/data/references/partials/configuration.md
+++ b/src/data/references/partials/configuration.md
@@ -5,8 +5,8 @@
 View partials reside in `app/views/partials/`. Commands and queries reside in `app/lib/`. The path in render/function maps directly:
 
 - `{% render 'products/card' %}` → `app/views/partials/products/card.liquid`
-- `{% function r = 'lib/commands/products/create' %}` → `app/lib/commands/products/create.liquid`
-- `{% function r = 'lib/queries/products/search' %}` → `app/lib/queries/products/search.liquid`
+- `{% function r = 'commands/products/create' %}` → `app/lib/commands/products/create.liquid`
+- `{% function r = 'queries/products/search' %}` → `app/lib/queries/products/search.liquid`
 
 ## Naming Rules
 
@@ -68,7 +68,7 @@ Variables must be explicitly passed. The partial cannot access the caller's scop
 ### function (returns data via return tag)
 
 ```liquid
-{% function result = 'lib/commands/products/create', title: "New", price: 19.99 %}
+{% function result = 'commands/products/create', title: "New", price: 19.99 %}
 ```
 
 The partial must use `{% return value %}` to send data back.
diff --git a/src/data/references/partials/gotchas.md b/src/data/references/partials/gotchas.md
index c2ff83d..c035793 100644
--- a/src/data/references/partials/gotchas.md
+++ b/src/data/references/partials/gotchas.md
@@ -31,7 +31,7 @@ data and display it. They have no concept of "what page called me" or what conte
 ```liquid
 {# WRONG — GraphQL in partial: #}
 {% comment %}@prompt: Shows user profile{% endcomment %}
-{% graphql g = 'lib/queries/users/find', id: context.params.id %}
+{% graphql g = 'users/find', id: context.params.id %}
 {{ g.user.email }}
 
 {# RIGHT — receive data as parameter: #}
@@ -41,7 +41,7 @@ data and display it. They have no concept of "what page called me" or what conte
 
 ```liquid
 {# In the page that renders it: #}
-{% graphql g = 'lib/queries/users/find', id: context.params.id %}
+{% graphql g = 'users/find', id: context.params.id %}
 {% render 'users/profile', user: g.user %}
 ```
 
diff --git a/src/data/references/partials/patterns.md b/src/data/references/partials/patterns.md
index 48b286e..3795a66 100644
--- a/src/data/references/partials/patterns.md
+++ b/src/data/references/partials/patterns.md
@@ -44,18 +44,32 @@ Wrap a GraphQL call location in a query partial so the actual graphql tag stays
 
 ## Command Partial Pattern
 
-See [Commands](../commands/README.md) for the full build/check/execute pattern.
+See [Commands](../commands/README.md) for the full build/check/execute
+pattern. The command is **three** files: orchestrator + sibling
+`build.liquid` + sibling `check.liquid`. There is **no**
+`modules/core/commands/build` / `…/check` — only `commands/execute`
+runs at the module level.
 
 ```liquid
 {% comment %} app/lib/commands/products/create.liquid {% endcomment %}
-{% assign object = { "title": title, "price": price } %}
-{% function object = 'modules/core/commands/build', object: object %}
-{% assign validators = [{ "name": "presence", "property": "title" }] %}
-{% function object = 'modules/core/commands/check', object: object, validators: validators %}
-{% if object.valid %}
-  {% function object = 'modules/core/commands/execute', mutation_name: 'products/create', selection: 'record_create', object: object %}
-{% endif %}
-{% return object %}
+{% doc %}
+  @param {object} params - raw input
+{% enddoc %}
+{% liquid
+  function object = 'commands/products/create/build', object: params
+  function object = 'commands/products/create/check', object: object
+
+  if object.valid == false
+    return object
+  endif
+
+  function object = 'modules/core/commands/execute',
+    mutation_name: 'products/create',
+    selection: 'record_create',
+    object: object
+
+  return object
+%}
 ```
 
 ## Form Partial with Validation Errors
diff --git a/src/data/resources/ok-platformos-development-guide.md b/src/data/resources/ok-platformos-development-guide.md
index a4f44b5..663861f 100644
--- a/src/data/resources/ok-platformos-development-guide.md
+++ b/src/data/resources/ok-platformos-development-guide.md
@@ -448,8 +448,8 @@ Validates the built object:
 {% liquid
   assign c = '{ "errors": {}, "valid": true }' | parse_json
 
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title'
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body'
+  function c = 'modules/core/lib/validations/presence', c: c, field_name: 'title', object: object
+  function c = 'modules/core/lib/validations/presence', c: c, field_name: 'body',  object: object
 
   assign object = object | hash_merge: valid: c.valid, errors: c.errors
 
diff --git a/src/data/resources/short-platformos-development-guide.md b/src/data/resources/short-platformos-development-guide.md
index 21c47a3..d2a17dd 100644
--- a/src/data/resources/short-platformos-development-guide.md
+++ b/src/data/resources/short-platformos-development-guide.md
@@ -408,8 +408,8 @@ Validates the built object:
 {% liquid
   assign c = '{ "errors": {}, "valid": true }' | parse_json
 
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'title'
-  function c = 'modules/core/validations/presence', c: c, object: object, field_name: 'body'
+  function c = 'modules/core/lib/validations/presence', c: c, field_name: 'title', object: object
+  function c = 'modules/core/lib/validations/presence', c: c, field_name: 'body',  object: object
 
   assign object = object | hash_merge: valid: c.valid, errors: c.errors
 
diff --git a/src/http-server.js b/src/http-server.js
index 234eb28..0ae5dcd 100644
--- a/src/http-server.js
+++ b/src/http-server.js
@@ -16,6 +16,8 @@ import { addPromotedRule, removePromotedRule, listPromotedRules } from './core/r
 import { reloadRules, loadAllRules } from './core/rules/index.js';
 import { runRules, getDisabledRules, getAllChecksWithRules, getRulesForCheck, getDisabledRuleDetails, getForceEnabledRules, getForceDisabledRules } from './core/rules/engine.js';
 import { loadOverrides, addForceEnable, addForceDisable, removeOverride } from './core/rule-overrides.js';
+import { loadCacConfig, updateCacConfig, defaultCacConfig, VALID_MODES, VALID_ACTIONS } from './core/cac-config.js';
+import { getRecentCacDecisions } from './core/cac-predictor.js';
 import { extractParams, templateOf, KNOWN_EXTRACTOR_CHECKS } from './core/diagnostic-record.js';
 import { buildFactGraph } from './core/project-fact-graph.js';
 
@@ -23,7 +25,7 @@ import { buildFactGraph } from './core/project-fact-graph.js';
  * HTTP server — REST endpoints for tool discovery, execution, and resources.
  * MCP protocol (JSON-RPC over stdio) is handled by the SDK transport in server.js.
  */
-export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild, onOverridesChanged, switchEngineMode, getEngineMode }) {
+export function startHttp(registry, { port, log, version, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild, onOverridesChanged, onCacConfigChanged, switchEngineMode, getEngineMode }) {
   if (!port) return null;
 
   const dashboardHtml = buildDashboardHtml();
@@ -173,6 +175,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
       if (url.pathname === '/api/engine/rule-overrides') {
         return handleRuleOverridesMutate(projectDir, body, res, log, onOverridesChanged);
       }
+
+      if (url.pathname === '/api/cac/config') {
+        return handleCacConfigMutate(projectDir, body, res, log, onCacConfigChanged);
+      }
     }
 
     // ── Analytics GET routes ──────────────────────────────────────────────
@@ -267,6 +273,15 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
     // POST on this path is dispatched inside the POST block above so the
     // shared body-parser isn't read twice.
 
+    if (method === 'GET' && url.pathname === '/api/cac/config') {
+      return handleCacConfigGet(projectDir, res, log);
+    }
+
+    if (method === 'GET' && url.pathname === '/api/cac/decisions') {
+      return handleCacDecisions(url, res);
+    }
+    // POST /api/cac/config is dispatched inside the POST block above.
+
     // ── Fallback ────────────────────────────────────────────────────────
     sendJson(res, 404, { error: 'Not found' });
   });
@@ -1229,6 +1244,79 @@ function handleRuleOverridesMutate(projectDir, body, res, log, onOverridesChange
   }
 }
 
+// ── CAC predictor (Cohen's Agentic Conjecture) ───────────────────────────
+//
+// Opt-in 4th gating axis. The validator behaves identically to a build
+// without the predictor when `enabled: false`. These endpoints expose the
+// persisted config + recent decision telemetry to the dashboard.
+
+function handleCacConfigGet(projectDir, res, log) {
+  try {
+    const state = loadCacConfig(projectDir, { log });
+    sendJson(res, 200, {
+      config: state,
+      defaults: defaultCacConfig(),
+      valid_modes: VALID_MODES,
+      valid_actions: VALID_ACTIONS,
+    });
+  } catch (e) {
+    sendJson(res, 500, { error: e.message });
+  }
+}
+
+/**
+ * POST /api/cac/config
+ *
+ * Body: any subset of `{ enabled, mode, threshold, action, min_samples }`.
+ * Unknown keys are dropped; out-of-range values are coerced to defaults.
+ * The `onCacConfigChanged` hook re-reads the file into the live ref so the
+ * change takes effect immediately for in-flight validate_code calls
+ * (without requiring a server restart).
+ */
+function handleCacConfigMutate(projectDir, body, res, log, onCacConfigChanged) {
+  if (!body || typeof body !== 'object') {
+    return sendJson(res, 400, { error: 'body required' });
+  }
+  try {
+    const state = updateCacConfig(projectDir, body, { log });
+    try { onCacConfigChanged?.(); } catch (e) { log?.(`onCacConfigChanged failed: ${e.message}`); }
+    sendJson(res, 200, { config: state });
+  } catch (e) {
+    sendJson(res, 500, { error: e.message });
+  }
+}
+
+function handleCacDecisions(url, res) {
+  const limit = clampInt(url.searchParams.get('limit'), 1, 200, 50);
+  try {
+    const decisions = getRecentCacDecisions(limit);
+    sendJson(res, 200, {
+      count: decisions.length,
+      decisions,
+      summary: summarizeCacDecisions(decisions),
+    });
+  } catch (e) {
+    sendJson(res, 500, { error: e.message });
+  }
+}
+
+function summarizeCacDecisions(decisions) {
+  const out = { allow: 0, downgrade: 0, suppress: 0, by_feature: {}, by_mode: {} };
+  for (const d of decisions) {
+    const dec = d.decision || 'allow';
+    out[dec] = (out[dec] ?? 0) + 1;
+    out.by_feature[d.feature] = (out.by_feature[d.feature] ?? 0) + 1;
+    out.by_mode[d.mode] = (out.by_mode[d.mode] ?? 0) + 1;
+  }
+  return out;
+}
+
+function clampInt(raw, min, max, fallback) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────
 
 function sendJson(res, status, data) {
diff --git a/src/server.js b/src/server.js
index af54a19..687b7a8 100644
--- a/src/server.js
+++ b/src/server.js
@@ -17,6 +17,8 @@ import { initPromotedRules, reloadRules } from './core/rules/index.js';
 import { updateDisabledRules, updateForceOverrides, setDisabledRuleDetails } from './core/rules/engine.js';
 import { ruleScores, resolveProbation } from './core/case-base.js';
 import { loadOverrides, overrideSets } from './core/rule-overrides.js';
+import { loadCacConfig } from './core/cac-config.js';
+import { rehydrateRecentCacDecisions } from './core/cac-predictor.js';
 import { loadEngineMode, isAdaptive, setEngineMode, getEngineMode } from './core/engine-mode.js';
 import { startHttp } from './http-server.js';
 import { createLogger } from './core/logger.js';
@@ -160,6 +162,36 @@ export async function createServer({ projectDir, httpPort = 0 }) {
   syncRuleOverrides();
   syncDisabledRules();
 
+  // ── CAC predictor config (opt-in 4th gating axis) ──────────────────────────
+  // Shared mutable ref: validate-code reads `current` on each call, the HTTP
+  // POST handler mutates it after persisting to disk. Disabled by default —
+  // when `enabled: false`, validate-code skips the predictor entirely.
+  const cacConfigState = { current: loadCacConfig(projectDir, { log }) };
+  function syncCacConfig() {
+    try {
+      cacConfigState.current = loadCacConfig(projectDir, { log });
+      const c = cacConfigState.current;
+      if (c.enabled) {
+        log(`cac-predictor: ${c.mode} mode, threshold=${c.threshold}, action=${c.action}, min_samples=${c.min_samples}`);
+      }
+    } catch (e) {
+      log(`cac-predictor: sync failed (${e.message})`);
+    }
+  }
+  syncCacConfig();
+
+  // Rehydrate the CAC decision ring from prior sessions' NDJSON logs so the
+  // dashboard's "Recent CAC Decisions" panel survives server restarts. Pure
+  // disk read — runs even when the predictor is disabled, since flipping it
+  // on later in the session shouldn't show an empty audit trail. Best
+  // effort: any I/O error returns 0 and is logged at info level.
+  try {
+    const n = rehydrateRecentCacDecisions(sessionsDir);
+    if (n > 0) log(`cac-predictor: rehydrated ${n} decision(s) from prior sessions`);
+  } catch (e) {
+    log(`cac-predictor: rehydration failed (${e.message})`);
+  }
+
   // ── Engine mode transitions ──────────────────────────────────────────────────
   function handleModeTransition(prev, mode) {
     log(`engine-mode: ${prev} → ${mode}`);
@@ -625,6 +657,7 @@ export async function createServer({ projectDir, httpPort = 0 }) {
     sessionBus,
     blobStore,
     analyticsStore,
+    cacConfigState,
     log,
     emit,
     switchEngineMode,
@@ -727,7 +760,7 @@ export async function createServer({ projectDir, httpPort = 0 }) {
       };
     }
     const dataRoot = join(__dirname, 'data');
-    startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild: syncDisabledRules, onOverridesChanged: () => { syncRuleOverrides(); syncDisabledRules(); }, switchEngineMode, getEngineMode });
+    startHttp(registry, { port: httpPort, log, version: VERSION, logPath, getStatus, restartLsp, dataRoot, subscribeToEvents, posCliPath, projectDir, sessionsDir, saveSessionSummary, analyticsStore, blobStore, onAnalyticsRebuild: syncDisabledRules, onOverridesChanged: () => { syncRuleOverrides(); syncDisabledRules(); }, onCacConfigChanged: syncCacConfig, switchEngineMode, getEngineMode });
   }
 
   // ── Graceful shutdown ─────────────────────────────────────────────────────
diff --git a/src/tools/analyze-project.js b/src/tools/analyze-project.js
index b72a873..467462c 100644
--- a/src/tools/analyze-project.js
+++ b/src/tools/analyze-project.js
@@ -510,25 +510,25 @@ function performIntegrityChecks(projectMap) {
   }
 
   // 3. Broken function calls (from pages, partials, commands, queries)
-  // In platformOS, both `{% function result = 'queries/X' %}` and
-  // `{% function result = 'lib/queries/X' %}` resolve to
-  // `app/lib/queries/X.liquid`. The `lib/` prefix is OPTIONAL, the `app/`
-  // prefix is implicit. Naively prepending `app/lib/` to a call that
-  // already carries `lib/` produces phantom `app/lib/lib/...` paths and
-  // false-positive missing_command/missing_query issues.
+  //
+  // platformOS resolves `function` paths relative to the partial search
+  // paths declared by `@platformos/platformos-common`:
+  //   FILE_TYPE_DIRS[Partial] = ['views/partials', 'lib']
+  // joined under `app/`. So `'commands/X'` resolves to `app/lib/commands/X.liquid`,
+  // and `'lib/commands/X'` resolves to `app/lib/lib/commands/X.liquid`
+  // (which never exists). A literal `lib/` prefix is *invalid*, not optional.
+  // Reporting the resolution verbatim — without stripping `lib/` — surfaces
+  // the bug to the agent through the error message itself.
   const checkFunctionCalls = (sourcePath, functionCalls) => {
     for (const fc of functionCalls ?? []) {
       if (isModuleRef(fc.path)) continue;
-      // Strip optional leading `lib/` so `'lib/commands/X'` and `'commands/X'`
-      // both resolve to `app/lib/commands/X.liquid` consistently.
-      const stripped = fc.path.replace(/^lib\//, '');
-      const fullPath = `app/lib/${stripped}.liquid`;
-      if (stripped.includes('commands/') && !allCommands.has(fullPath)) {
+      const fullPath = `app/lib/${fc.path}.liquid`;
+      if (fc.path.includes('commands/') && !allCommands.has(fullPath)) {
         issues.push({
           type: 'missing_command', severity: 'error', source: sourcePath, target: fullPath,
           message: `'${sourcePath}' calls command '${fc.path}' (resolves to ${fullPath}) which does not exist`,
         });
-      } else if (stripped.includes('queries/') && !allQueries.has(fullPath)) {
+      } else if (fc.path.includes('queries/') && !allQueries.has(fullPath)) {
         issues.push({
           type: 'missing_query', severity: 'error', source: sourcePath, target: fullPath,
           message: `'${sourcePath}' calls query '${fc.path}' (resolves to ${fullPath}) which does not exist`,
@@ -537,13 +537,26 @@ function performIntegrityChecks(projectMap) {
     }
   };
 
-  for (const [slug, page] of Object.entries(projectMap.pages ?? {})) {
+  for (const [, page] of Object.entries(projectMap.pages ?? {})) {
     checkFunctionCalls(page.path, page.function_calls);
   }
-  // Also check function calls from partials, commands, and queries
-  for (const [name, partial] of Object.entries(projectMap.partials ?? {})) {
+  for (const [, partial] of Object.entries(projectMap.partials ?? {})) {
     checkFunctionCalls(partial.path, partial.function_calls);
   }
+  // Commands invoke their own build/check phases via {% function %}; queries
+  // and layouts also carry function_calls in the project map. Without these,
+  // a wrong call inside a command (the most common form: a multi-phase
+  // command calling its sibling phase with `lib/commands/...`) slips through
+  // unchecked.
+  for (const [path, cmd] of Object.entries(projectMap.commands ?? {})) {
+    checkFunctionCalls(path, cmd.function_calls);
+  }
+  for (const [path, query] of Object.entries(projectMap.queries ?? {})) {
+    checkFunctionCalls(path, query.function_calls);
+  }
+  for (const [, layout] of Object.entries(projectMap.layouts ?? {})) {
+    checkFunctionCalls(layout.path, layout.function_calls);
+  }
 
   // 4. Orphan partials (never rendered by anything) — shared predicate so
   //    validate_intent P5 and dependency-graph orphaned-file detection use the
diff --git a/src/tools/validate-code.js b/src/tools/validate-code.js
index 6a30c38..f97961c 100644
--- a/src/tools/validate-code.js
+++ b/src/tools/validate-code.js
@@ -13,6 +13,7 @@ import { validateTranslationYaml } from '../core/translation-validator.js';
 import { checkSchemaProperties } from '../core/schema-property-checker.js';
 import { runDiagnosticPipeline, stampDefaultsOn, suppressUpstreamFrontmatterDup } from '../core/diagnostic-pipeline.js';
 import { isCheckForceDisabled } from '../core/rules/engine.js';
+import { applyCac } from '../core/cac-predictor.js';
 import { partitionCallersByPending } from '../core/pending-callers.js';
 import { toUri, sanitizePath } from '../core/utils.js';
 import { fingerprint, templateFingerprint, messageTemplate, extractParams } from '../core/diagnostic-record.js';
@@ -789,6 +790,35 @@ explicitly only if you are validating a file that is NOT part of the most recent
       result.warnings = result.warnings.filter(dropForceDisabled);
       result.infos = result.infos.filter(dropForceDisabled);
 
+      // 12c. CAC predictor — opt-in 4th gating axis (Cohen's Agentic Conjecture).
+      //
+      //      Predicts P(adopted | rule_id, file_domain) from the analytics
+      //      store and either suppresses or downgrades emits whose predicted
+      //      adoption falls below the configured threshold. Disabled by
+      //      default; enabled per project via the dashboard. When disabled,
+      //      this step is a no-op (`applyCac` returns immediately on
+      //      !config.enabled). When enabled in `shadow` mode, decisions are
+      //      recorded for analysis but no diagnostics are mutated. Skipped
+      //      for live-console calls (ctx.untracked) so experimental runs
+      //      don't fight the gate.
+      //
+      //      Wrapped in try/catch — predictor failure must NEVER break
+      //      validate_code. The whole layer is decoupled in src/core/cac-*.
+      const cacConfig = ctx.cacConfigState?.current;
+      if (cacConfig?.enabled && !ctx.untracked) {
+        try {
+          applyCac(result, {
+            config: cacConfig,
+            analyticsStore: ctx.analyticsStore,
+            filePath: file_path,
+            sessionBus: ctx.sessionBus,
+            log: ctx.log,
+          });
+        } catch (e) {
+          ctx.log?.(`cac-predictor: applyCac threw (${e?.message ?? e}); diagnostics passed through`);
+        }
+      }
+
       // 12. Strip null hint fields — diagnostics without hints should omit the field
       // entirely rather than returning hint: null which looks like a bug in the output.
       for (const d of [...result.errors, ...result.warnings, ...result.infos]) {
diff --git a/tests/integration/analyze-project-lib-prefix.integration.test.js b/tests/integration/analyze-project-lib-prefix.integration.test.js
index 6994b68..2c58f45 100644
--- a/tests/integration/analyze-project-lib-prefix.integration.test.js
+++ b/tests/integration/analyze-project-lib-prefix.integration.test.js
@@ -1,19 +1,30 @@
 /**
- * Regression test for the `app/lib/lib/...` phantom-path bug in
- * analyze_project (2026-04-26).
+ * Regression test for the `lib/`-prefix correctness contract in
+ * `analyze_project` (2026-04-29).
  *
- * Cause: `src/tools/analyze-project.js` previously joined function-call
- * paths as `app/lib/${fc.path}.liquid` without stripping an optional
- * leading `lib/`. In platformOS, both `{% function = 'commands/X' %}` and
- * `{% function = 'lib/commands/X' %}` are valid call forms — they both
- * resolve to `app/lib/commands/X.liquid`. The naive join produced
- * `app/lib/lib/commands/X.liquid` and then complained that the phantom
- * file did not exist.
+ * History — the previous version of this test pinned the inverse claim:
+ * that `'commands/X'` and `'lib/commands/X'` were both valid call forms.
+ * That assumption was wrong. platformOS resolves `function` paths under
+ * the partial search paths declared by `@platformos/platformos-common`:
  *
- * Fix: `analyze-project.js` now strips the optional `lib/` prefix before
- * joining, mirroring the resolution in `error-enricher.js` /
- * `core/rules/queries.js` / `fix-generator.js` /
- * `core/diagnostic-pipeline.js`.
+ *   FILE_TYPE_DIRS[Partial] = ['views/partials', 'lib']
+ *
+ * joined under `app/`. So `'commands/X'` is found at `app/lib/commands/X.liquid`
+ * and `'lib/commands/X'` is searched at `app/lib/lib/commands/X.liquid` — a
+ * directory that never exists in any sane project. Stripping the `lib/`
+ * prefix in `analyze-project.js` silently suppressed real errors AND
+ * matched the buggy stripping in `core/diagnostic-pipeline.js` /
+ * `error-enricher.js` / `core/rules/queries.js` / `fix-generator.js`,
+ * so the false assumption propagated end-to-end.
+ *
+ * The new contract:
+ *   • `commands/X` (bare) is canonical; if the file exists, no issue.
+ *   • `lib/commands/X` resolves to `app/lib/lib/commands/X.liquid`,
+ *     which never exists, so analyze_project MUST flag it as a
+ *     missing_command and surface the doubled `lib/lib/` path in the
+ *     resolution string (so the agent sees what platformOS actually does).
+ *   • A genuinely missing command (under the bare `commands/` form) is
+ *     still reported with the canonical single-`lib/` resolution.
  */
 
 import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test';
@@ -29,8 +40,10 @@ let proj;
 beforeAll(async () => {
   proj = createTempProject(FIXTURE_DIR);
 
-  // Create a real command + a build phase that the page calls under both
-  // call-form shapes. Both should resolve to the SAME file on disk.
+  // Real command + a build phase that the orchestrator calls under both
+  // shapes. The bare `commands/...` call must resolve cleanly; the
+  // `lib/commands/...` call must be flagged as wrong even though a file
+  // with the lib/-stripped name exists on disk.
   const cmdDir = join(proj.dir, 'app/lib/commands/contacts/create');
   mkdirSync(cmdDir, { recursive: true });
   writeFileSync(
@@ -54,8 +67,8 @@ beforeAll(async () => {
     'utf8',
   );
 
-  // Page that calls a command which DOES NOT exist on disk — exercises the
-  // false-negative guard (genuine miss must still be flagged).
+  // Page that calls a command which DOES NOT exist on disk — exercises
+  // the canonical missing-command path (no `lib/` prefix involved).
   mkdirSync(join(proj.dir, 'app/views/pages/contacts'), { recursive: true });
   writeFileSync(
     join(proj.dir, 'app/views/pages/contacts/test_miss.html.liquid'),
@@ -79,37 +92,38 @@ afterAll(() => {
   proj?.cleanup();
 });
 
-describe("analyze_project — function-call resolution doesn't double the lib/ prefix", () => {
-  it('does NOT emit missing_command for `lib/commands/X` when the file exists at app/lib/commands/X.liquid', async () => {
+describe("analyze_project — `lib/` prefix is invalid, never optional", () => {
+  it('does NOT flag the bare `commands/X` form when the file exists at app/lib/commands/X.liquid', async () => {
     const result = await server.callTool('analyze_project', {});
-    const phantom = result.integrity.filter(i =>
+    const flagged = result.integrity.filter(i =>
       i.type === 'missing_command' &&
-      // Phantom path would carry double `lib/lib/`.
-      (/app\/lib\/lib\//.test(i.target ?? '') || /app\/lib\/lib\//.test(i.message ?? ''))
+      (i.message ?? '').includes("'commands/contacts/create/build'")
     );
-    if (phantom.length > 0) {
-      console.log('Phantom missing_command issues:', phantom);
-    }
-    expect(phantom).toHaveLength(0);
+    expect(flagged).toHaveLength(0);
   });
 
-  it('also does not flag the bare `commands/X` form when the file exists', async () => {
+  it('FLAGS `lib/commands/X` as missing — the literal prefix expands to `app/lib/lib/...` and never resolves', async () => {
     const result = await server.callTool('analyze_project', {});
     const flagged = result.integrity.filter(i =>
       i.type === 'missing_command' &&
-      (i.message ?? '').includes("'commands/contacts/create/build'")
+      (i.message ?? '').includes("'lib/commands/contacts/create/build'")
     );
-    expect(flagged).toHaveLength(0);
+    expect(flagged.length).toBeGreaterThan(0);
+    // The reported target path shows the doubled `lib/` so the agent sees
+    // exactly what platformOS would search at runtime.
+    expect(flagged[0].target).toBe('app/lib/lib/commands/contacts/create/build.liquid');
+    expect(flagged[0].message).toContain('app/lib/lib/commands/contacts/create/build.liquid');
   });
 
-  it('still flags genuinely missing commands (no false negative)', async () => {
+  it('still flags genuinely missing commands under the canonical (single-`lib/`) form', async () => {
     const result = await server.callTool('analyze_project', {});
     const miss = result.integrity.filter(i =>
       i.type === 'missing_command' &&
       (i.message ?? '').includes('commands/contacts/never_written')
     );
     expect(miss.length).toBeGreaterThan(0);
-    // The reported target path uses the canonical resolution (single lib/).
     expect(miss[0].target).toBe('app/lib/commands/contacts/never_written.liquid');
+    // No accidental doubling on the canonical form
+    expect(miss[0].target).not.toMatch(/app\/lib\/lib\//);
   });
 });
diff --git a/tests/integration/cac/toggle.test.js b/tests/integration/cac/toggle.test.js
new file mode 100644
index 0000000..63d8462
--- /dev/null
+++ b/tests/integration/cac/toggle.test.js
@@ -0,0 +1,178 @@
+/**
+ * CAC predictor — end-to-end toggle test.
+ *
+ * Verifies the opt-in 4th gating axis is wired correctly through:
+ *   - server boot (defaults loaded, disabled by default)
+ *   - HTTP endpoints (GET/POST /api/cac/config, GET /api/cac/decisions)
+ *   - validate_code integration (no behavior change when disabled,
+ *     decisions recorded in shadow mode, suppression in active mode)
+ *   - hot-reload (POST changes take effect on the very next validate_code
+ *     call without restart)
+ *
+ * The `force-disable-check.test.js` was the structural template for this
+ * test (POST → validate → assert → clear → re-assert).
+ */
+
+import { describe, it, expect, beforeAll, afterAll, setDefaultTimeout } from 'bun:test';
+import { startServer, FIXTURE_DIR, createTempProject } from '../helpers/server.js';
+import { loadCacConfig } from '../../../src/core/cac-config.js';
+
+setDefaultTimeout(60_000);
+
+let server;
+let proj;
+
+// File chosen for the same reason force-disable-check.test.js picks it: pure
+// HTML page with no partial renders → reliably triggers
+// pos-supervisor:HtmlInPage. The CAC layer needs at least one diagnostic to
+// chew on for shadow-mode telemetry to record an entry.
+const FILE = 'app/views/pages/cac-toggle-test.liquid';
+const CONTENT = '---\nslug: cac-toggle-test\n---\n
        hi
        \n';
+
+beforeAll(async () => {
+  proj = createTempProject(FIXTURE_DIR);
+  server = await startServer(proj.dir);
+});
+
+afterAll(() => {
+  server?.stop();
+  proj?.cleanup();
+});
+
+async function runValidate() {
+  return server.callTool('validate_code', { file_path: FILE, content: CONTENT, mode: 'quick' });
+}
+
+async function getCacConfig() {
+  const r = await fetch(server.baseUrl + '/api/cac/config');
+  return r.json();
+}
+
+async function setCacConfig(patch) {
+  const r = await fetch(server.baseUrl + '/api/cac/config', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(patch),
+  });
+  return { status: r.status, body: await r.json() };
+}
+
+async function getCacDecisions(limit = 50) {
+  const r = await fetch(server.baseUrl + `/api/cac/decisions?limit=${limit}`);
+  return r.json();
+}
+
+describe('CAC predictor: HTTP toggle + validate_code integration', () => {
+  it('GET /api/cac/config returns defaults; CAC is disabled out of the box', async () => {
+    const r = await getCacConfig();
+    expect(r.config.enabled).toBe(false);
+    expect(r.config.mode).toBe('shadow');
+    expect(r.defaults).toBeDefined();
+    expect(Array.isArray(r.valid_modes)).toBe(true);
+    expect(r.valid_modes).toContain('shadow');
+    expect(r.valid_modes).toContain('active');
+  });
+
+  it('disabled: validate_code is unaffected; no decisions recorded', async () => {
+    // Sanity: predictor disabled means no entries appear from this call.
+    // Note: another describe block running first could have populated
+    // decisions, so we check the contract (count is finite + all entries
+    // come from earlier shadow/active runs only) by inspecting `summary`.
+    const before = await getCacDecisions();
+    const beforeCount = before.count;
+
+    const res = await runValidate();
+    const all = [...(res.errors ?? []), ...(res.warnings ?? [])];
+    expect(all.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true);
+
+    const after = await getCacDecisions();
+    // The disabled predictor must not append anything.
+    expect(after.count).toBe(beforeCount);
+  });
+
+  it('shadow mode: records decisions but does NOT modify diagnostics', async () => {
+    const setResp = await setCacConfig({ enabled: true, mode: 'shadow', threshold: 0.99, action: 'suppress' });
+    expect(setResp.status).toBe(200);
+    expect(setResp.body.config.enabled).toBe(true);
+    expect(setResp.body.config.mode).toBe('shadow');
+    // Persistence: the file should now exist on disk with the patched values.
+    const fromDisk = loadCacConfig(proj.dir);
+    expect(fromDisk.enabled).toBe(true);
+    expect(fromDisk.threshold).toBe(0.99);
+
+    const before = await getCacDecisions();
+    const beforeCount = before.count;
+    const res = await runValidate();
+
+    // Diagnostic still present — shadow mode never mutates result.
+    const all = [...(res.errors ?? []), ...(res.warnings ?? [])];
+    expect(all.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true);
+
+    // But decisions ring buffer grew.
+    const after = await getCacDecisions();
+    expect(after.count).toBeGreaterThan(beforeCount);
+    // Each new decision is tagged with shadow mode.
+    const fresh = after.decisions.slice(beforeCount);
+    expect(fresh.every(d => d.mode === 'shadow')).toBe(true);
+  });
+
+  it('active mode + suppress: drops below-threshold diagnostics', async () => {
+    // Threshold 0.99 + action suppress: any diagnostic that has actual signal
+    // and predicts < 0.99 adoption gets dropped. With an empty analytics
+    // store the predictor falls to feature='prior' and ALWAYS allows. So we
+    // can't reliably suppress without seeded data — instead, assert the
+    // contract: when feature='prior', decision is 'allow' regardless of
+    // threshold. (Suppression on real data is covered by the unit tests in
+    // tests/unit/cac-predictor.test.js where we inject a deterministic
+    // historyProvider.) Here we verify only that flipping to active does not
+    // crash and does not over-suppress when there's no signal.
+    const setResp = await setCacConfig({ enabled: true, mode: 'active', threshold: 0.99, action: 'suppress' });
+    expect(setResp.status).toBe(200);
+    expect(setResp.body.config.mode).toBe('active');
+
+    const res = await runValidate();
+    const all = [...(res.errors ?? []), ...(res.warnings ?? [])];
+    // Without analytics history every diagnostic falls to prior → allow.
+    expect(all.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true);
+
+    const dec = await getCacDecisions();
+    const recent = dec.decisions.at(-1);
+    expect(recent.mode).toBe('active');
+    expect(['allow', 'suppress', 'downgrade']).toContain(recent.decision);
+  });
+
+  it('disabling resets behavior immediately (no restart needed)', async () => {
+    const setResp = await setCacConfig({ enabled: false });
+    expect(setResp.status).toBe(200);
+    expect(setResp.body.config.enabled).toBe(false);
+
+    const before = await getCacDecisions();
+    const res = await runValidate();
+    const all = [...(res.errors ?? []), ...(res.warnings ?? [])];
+    expect(all.some(d => d.check === 'pos-supervisor:HtmlInPage')).toBe(true);
+    const after = await getCacDecisions();
+    expect(after.count).toBe(before.count); // disabled: no append
+  });
+
+  it('POST with garbage body returns 400, leaves state untouched', async () => {
+    const r = await fetch(server.baseUrl + '/api/cac/config', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: 'not-json',
+    });
+    expect([400, 500]).toContain(r.status); // body parser error → 400 (sometimes 500 from JSON)
+  });
+
+  it('POST with unknown keys: known fields applied, unknown silently dropped', async () => {
+    const setResp = await setCacConfig({ enabled: true, mode: 'shadow', threshold: 0.5, sneaky: 'no' });
+    expect(setResp.status).toBe(200);
+    expect(setResp.body.config.threshold).toBe(0.5);
+    expect(setResp.body.config).not.toHaveProperty('sneaky');
+  });
+
+  it('POST with out-of-range threshold gets coerced to default', async () => {
+    const setResp = await setCacConfig({ threshold: 99 });
+    expect(setResp.status).toBe(200);
+    expect(setResp.body.config.threshold).toBeGreaterThan(0);
+    expect(setResp.body.config.threshold).toBeLessThan(1);
+  });
+});
diff --git a/tests/unit/cac-config.test.js b/tests/unit/cac-config.test.js
new file mode 100644
index 0000000..f9c750f
--- /dev/null
+++ b/tests/unit/cac-config.test.js
@@ -0,0 +1,121 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  loadCacConfig, saveCacConfig, updateCacConfig,
+  defaultCacConfig, VALID_MODES, VALID_ACTIONS,
+} from '../../src/core/cac-config.js';
+
+let projectDir;
+
+beforeEach(() => {
+  projectDir = join(tmpdir(), `pos-cac-cfg-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(projectDir, { recursive: true });
+});
+
+afterEach(() => {
+  try { rmSync(projectDir, { recursive: true, force: true }); } catch {}
+});
+
+describe('cac-config: defaults + load', () => {
+  test('default state is disabled, shadow mode', () => {
+    const def = defaultCacConfig();
+    expect(def.enabled).toBe(false);
+    expect(def.mode).toBe('shadow');
+    expect(def.action).toBe('downgrade');
+    expect(def.threshold).toBeGreaterThan(0);
+    expect(def.threshold).toBeLessThan(1);
+    expect(def.min_samples).toBeGreaterThanOrEqual(1);
+  });
+
+  test('VALID_MODES and VALID_ACTIONS exposed for UI', () => {
+    expect(VALID_MODES).toContain('shadow');
+    expect(VALID_MODES).toContain('active');
+    expect(VALID_ACTIONS).toContain('downgrade');
+    expect(VALID_ACTIONS).toContain('suppress');
+  });
+
+  test('loadCacConfig on missing file returns defaults (no throw)', () => {
+    const s = loadCacConfig(projectDir);
+    expect(s).toEqual(defaultCacConfig());
+  });
+
+  test('loadCacConfig on malformed JSON returns defaults + logs', () => {
+    const path = join(projectDir, '.pos-supervisor', 'cac-config.json');
+    mkdirSync(join(projectDir, '.pos-supervisor'), { recursive: true });
+    writeFileSync(path, '{not json');
+    let logged = null;
+    const s = loadCacConfig(projectDir, { log: (m) => { logged = m; } });
+    expect(s).toEqual(defaultCacConfig());
+    expect(logged).toContain('failed to parse');
+  });
+});
+
+describe('cac-config: save + round-trip', () => {
+  test('saveCacConfig persists and round-trips', () => {
+    saveCacConfig(projectDir, { enabled: true, mode: 'active', threshold: 0.5, action: 'suppress', min_samples: 10 });
+    const loaded = loadCacConfig(projectDir);
+    expect(loaded.enabled).toBe(true);
+    expect(loaded.mode).toBe('active');
+    expect(loaded.threshold).toBe(0.5);
+    expect(loaded.action).toBe('suppress');
+    expect(loaded.min_samples).toBe(10);
+  });
+
+  test('saveCacConfig coerces invalid mode to default', () => {
+    saveCacConfig(projectDir, { enabled: true, mode: 'turbo', threshold: 0.4 });
+    const loaded = loadCacConfig(projectDir);
+    expect(loaded.mode).toBe('shadow');     // coerced from invalid
+    expect(loaded.threshold).toBe(0.4);     // valid, kept
+    expect(loaded.enabled).toBe(true);      // valid, kept
+  });
+
+  test('saveCacConfig clamps out-of-range threshold to default', () => {
+    saveCacConfig(projectDir, { threshold: 1.5 });
+    const loaded = loadCacConfig(projectDir);
+    expect(loaded.threshold).toBe(defaultCacConfig().threshold);
+  });
+
+  test('saveCacConfig rejects negative min_samples', () => {
+    saveCacConfig(projectDir, { min_samples: -3 });
+    const loaded = loadCacConfig(projectDir);
+    expect(loaded.min_samples).toBe(defaultCacConfig().min_samples);
+  });
+
+  test('saveCacConfig writes valid JSON file with version', () => {
+    saveCacConfig(projectDir, { enabled: true });
+    const path = join(projectDir, '.pos-supervisor', 'cac-config.json');
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.version).toBe(1);
+    expect(parsed.enabled).toBe(true);
+  });
+});
+
+describe('cac-config: update (patch)', () => {
+  test('updateCacConfig merges into existing state', () => {
+    saveCacConfig(projectDir, { enabled: true, threshold: 0.4 });
+    const next = updateCacConfig(projectDir, { mode: 'active' });
+    expect(next.enabled).toBe(true);     // preserved
+    expect(next.threshold).toBe(0.4);    // preserved
+    expect(next.mode).toBe('active');    // patched
+  });
+
+  test('updateCacConfig drops unknown keys silently', () => {
+    const next = updateCacConfig(projectDir, { enabled: true, sneaky: 42 });
+    expect(next.enabled).toBe(true);
+    expect(next).not.toHaveProperty('sneaky');
+  });
+});
+
+describe('cac-config: file-state guarantees', () => {
+  test('force_enable not object would corrupt rule-overrides — verify cac is robust to similar', () => {
+    const path = join(projectDir, '.pos-supervisor', 'cac-config.json');
+    mkdirSync(join(projectDir, '.pos-supervisor'), { recursive: true });
+    writeFileSync(path, JSON.stringify({ version: 1, enabled: 'lol' }));
+    const loaded = loadCacConfig(projectDir);
+    // 'lol' is not a boolean → coerced to default
+    expect(loaded.enabled).toBe(false);
+  });
+});
diff --git a/tests/unit/cac-predictor.test.js b/tests/unit/cac-predictor.test.js
new file mode 100644
index 0000000..5fb50b8
--- /dev/null
+++ b/tests/unit/cac-predictor.test.js
@@ -0,0 +1,563 @@
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  scoreFixHelpfulness,
+  decideAction,
+  applyCac,
+  getRecentCacDecisions,
+  clearRecentCacDecisions,
+  loadRecentCacDecisions,
+  rehydrateRecentCacDecisions,
+} from '../../src/core/cac-predictor.js';
+import { defaultCacConfig } from '../../src/core/cac-config.js';
+import { makeEvent } from '../../src/core/session-events.js';
+
+beforeEach(() => {
+  clearRecentCacDecisions();
+});
+
+// ── scoreFixHelpfulness ────────────────────────────────────────────────────
+
+describe('scoreFixHelpfulness: hierarchy', () => {
+  test('uses (rule_id, file_domain) when its sample count meets min_samples', () => {
+    const historyProvider = (ruleId, domain) => {
+      if (ruleId === 'A.x' && domain === 'pages') return { adopted: 8, total: 10 };
+      if (ruleId === 'A.x' && domain === null)    return { adopted: 5, total: 50 };
+      return { adopted: 0, total: 0 };
+    };
+    const r = scoreFixHelpfulness({
+      rule_id: 'A.x',
+      severity: 'error',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider,
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+    });
+    expect(r.feature).toBe('rule_id+domain');
+    expect(r.n_samples).toBe(10);
+    expect(r.p_adopted).toBeGreaterThan(0.5);
+  });
+
+  test('falls back to (rule_id) when (rule_id+domain) is under-sampled', () => {
+    const historyProvider = (ruleId, domain) => {
+      if (ruleId === 'A.x' && domain === 'pages') return { adopted: 1, total: 2 };
+      if (ruleId === 'A.x' && domain === null)    return { adopted: 30, total: 100 };
+      return { adopted: 0, total: 0 };
+    };
+    const r = scoreFixHelpfulness({
+      rule_id: 'A.x',
+      severity: 'warning',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider,
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+    });
+    expect(r.feature).toBe('rule_id');
+    expect(r.n_samples).toBe(100);
+  });
+
+  test('falls back to severity when both rule levels are under-sampled', () => {
+    const r = scoreFixHelpfulness({
+      rule_id: 'A.x',
+      severity: 'error',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider: () => ({ adopted: 1, total: 2 }),
+      severityProvider: (sev) => sev === 'error' ? { adopted: 100, total: 500 } : { adopted: 0, total: 0 },
+    });
+    expect(r.feature).toBe('severity');
+    expect(r.n_samples).toBe(500);
+  });
+
+  test('returns prior with feature="prior" when nothing has signal', () => {
+    const r = scoreFixHelpfulness({
+      rule_id: 'A.x',
+      severity: 'error',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider: () => ({ adopted: 0, total: 0 }),
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+    });
+    expect(r.feature).toBe('prior');
+    expect(r.p_adopted).toBe(0.5);
+    expect(r.n_samples).toBe(0);
+  });
+
+  test('handles missing rule_id without throwing', () => {
+    const r = scoreFixHelpfulness({
+      rule_id: null,
+      severity: 'error',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider: () => ({ adopted: 0, total: 0 }),
+      severityProvider: (sev) => ({ adopted: 50, total: 100 }),
+    });
+    expect(r.feature).toBe('severity');
+    expect(r.n_samples).toBe(100);
+  });
+
+  test('history provider that throws is treated as zero samples', () => {
+    const r = scoreFixHelpfulness({
+      rule_id: 'A.x',
+      severity: 'error',
+      file_domain: 'pages',
+      min_samples: 5,
+      historyProvider: () => { throw new Error('db down'); },
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+    });
+    expect(r.feature).toBe('prior');
+  });
+});
+
+// ── decideAction ───────────────────────────────────────────────────────────
+
+describe('decideAction', () => {
+  const cfg = (overrides = {}) => ({ ...defaultCacConfig(), ...overrides });
+
+  test('feature=prior always allows', () => {
+    const d = decideAction(
+      { p_adopted: 0.0, feature: 'prior', n_samples: 0 },
+      cfg({ threshold: 0.99, action: 'suppress' }),
+    );
+    expect(d.decision).toBe('allow');
+    expect(d.reason).toBe('no_signal');
+  });
+
+  test('p_adopted >= threshold → allow', () => {
+    const d = decideAction(
+      { p_adopted: 0.7, feature: 'rule_id', n_samples: 30 },
+      cfg({ threshold: 0.5 }),
+    );
+    expect(d.decision).toBe('allow');
+    expect(d.reason).toBe('above_threshold');
+  });
+
+  test('p_adopted < threshold + action=suppress → suppress', () => {
+    const d = decideAction(
+      { p_adopted: 0.1, feature: 'rule_id', n_samples: 30 },
+      cfg({ threshold: 0.3, action: 'suppress' }),
+    );
+    expect(d.decision).toBe('suppress');
+  });
+
+  test('p_adopted < threshold + action=downgrade → downgrade', () => {
+    const d = decideAction(
+      { p_adopted: 0.1, feature: 'rule_id', n_samples: 30 },
+      cfg({ threshold: 0.3, action: 'downgrade' }),
+    );
+    expect(d.decision).toBe('downgrade');
+  });
+});
+
+// ── applyCac: integration ──────────────────────────────────────────────────
+
+function makeResult(diags) {
+  const result = { errors: [], warnings: [], infos: [] };
+  for (const d of diags) {
+    if (d.severity === 'error')        result.errors.push(d);
+    else if (d.severity === 'warning') result.warnings.push(d);
+    else                                result.infos.push(d);
+  }
+  return result;
+}
+
+describe('applyCac: gating', () => {
+  test('disabled config → no-op (result unchanged, no decisions)', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'm' },
+    ]);
+    const decisions = applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: false },
+      historyProvider: () => ({ adopted: 0, total: 100 }),
+    });
+    expect(result.errors).toHaveLength(1);
+    expect(decisions).toHaveLength(0);
+  });
+
+  test('shadow mode: records decision but never modifies result', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'm' },
+    ]);
+    const decisions = applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, action: 'suppress', min_samples: 5 },
+      historyProvider: (rid, dom) => rid === 'X.bad' ? { adopted: 0, total: 100 } : { adopted: 0, total: 0 },
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      filePath: 'app/views/pages/index.html.liquid',
+    });
+    expect(result.errors).toHaveLength(1);                  // not suppressed
+    expect(decisions).toHaveLength(1);
+    expect(decisions[0].decision.decision).toBe('suppress'); // would-be decision
+    const recorded = getRecentCacDecisions();
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].mode).toBe('shadow');
+  });
+
+  test('active mode + suppress: drops below-threshold diagnostic', () => {
+    const result = makeResult([
+      { severity: 'error',   check: 'X', rule_id: 'X.bad',  message: 'a' },
+      { severity: 'error',   check: 'Y', rule_id: 'Y.good', message: 'b' },
+      { severity: 'warning', check: 'Z', rule_id: 'Z.unk',  message: 'c' },
+    ]);
+    const decisions = applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'active', threshold: 0.4, action: 'suppress', min_samples: 5 },
+      historyProvider: (rid, dom) => {
+        if (rid === 'X.bad')  return { adopted: 1,  total: 100 }; // ~0.03 → suppress
+        if (rid === 'Y.good') return { adopted: 80, total: 100 }; // ~0.79 → allow
+        return { adopted: 0, total: 0 };
+      },
+      severityProvider: () => ({ adopted: 0, total: 0 }), // Z.unk falls to prior → allow
+      filePath: 'app/views/pages/index.html.liquid',
+    });
+    const remainingChecks = [...result.errors, ...result.warnings, ...result.infos].map(d => d.check);
+    expect(remainingChecks).not.toContain('X');
+    expect(remainingChecks).toContain('Y');
+    expect(remainingChecks).toContain('Z');
+    const xDec = decisions.find(d => d.check === 'X').decision.decision;
+    expect(xDec).toBe('suppress');
+  });
+
+  test('active mode + downgrade: reduces severity and rebalances buckets', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'active', threshold: 0.5, action: 'downgrade', min_samples: 5 },
+      historyProvider: () => ({ adopted: 1, total: 100 }),
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      filePath: 'app/views/pages/index.html.liquid',
+    });
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0].cac_downgraded).toBe(true);
+    expect(result.warnings[0].severity).toBe('warning');
+  });
+
+  test('active mode: error → warning → info on repeated downgrade', () => {
+    // Simulate two passes (pretend a rule fires twice on consecutive runs).
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    const cfg = { ...defaultCacConfig(), enabled: true, mode: 'active', threshold: 1.0, action: 'downgrade', min_samples: 5 };
+    const provider = () => ({ adopted: 0, total: 100 });
+    applyCac(result, { config: cfg, historyProvider: provider, severityProvider: () => ({ adopted: 0, total: 0 }), filePath: 'app/views/pages/i.liquid' });
+    expect(result.warnings[0].severity).toBe('warning');
+    applyCac(result, { config: cfg, historyProvider: provider, severityProvider: () => ({ adopted: 0, total: 0 }), filePath: 'app/views/pages/i.liquid' });
+    expect(result.infos[0].severity).toBe('info');
+  });
+
+  test('predictor failure does not throw — diagnostic passes through', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    let logged = '';
+    const decisions = applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'active', threshold: 0.5, action: 'suppress' },
+      historyProvider: () => { throw new Error('db down'); },
+      severityProvider: () => { throw new Error('db down'); },
+      filePath: 'app/views/pages/i.liquid',
+      log: (m) => { logged = m; },
+    });
+    // Even though both providers throw, scorer falls back to prior (allow) so
+    // the diagnostic survives. Predictor-level failure is caught at the
+    // scoring boundary via safeProvide.
+    expect(result.errors).toHaveLength(1);
+    expect(decisions).toHaveLength(1);
+  });
+
+  test('uses check fallback when rule_id missing — synthesizes .unmatched', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'OrphanedPartial', message: 'a' /* no rule_id */ },
+    ]);
+    const seen = [];
+    applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'active', threshold: 0.5, action: 'suppress', min_samples: 5 },
+      historyProvider: (rid, dom) => { seen.push([rid, dom]); return { adopted: 50, total: 100 }; },
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      filePath: 'app/views/partials/foo.liquid',
+    });
+    expect(seen.some(([rid]) => rid === 'OrphanedPartial.unmatched')).toBe(true);
+    expect(seen.some(([, dom]) => dom === 'partials')).toBe(true);
+  });
+
+  test('passes file_domain derived from filePath to the provider', () => {
+    const result = makeResult([
+      { severity: 'warning', check: 'X', rule_id: 'X.y', message: 'm' },
+    ]);
+    const calls = [];
+    applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, min_samples: 5 },
+      historyProvider: (rid, dom) => { calls.push([rid, dom]); return { adopted: 0, total: 0 }; },
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      filePath: 'app/lib/queries/blog_posts/search.graphql',
+    });
+    expect(calls).toContainEqual(['X.y', 'queries']);
+    expect(calls).toContainEqual(['X.y', null]);
+  });
+});
+
+describe('applyCac: telemetry ring buffer', () => {
+  test('records up to MAX_RECENT_DECISIONS most-recent entries', () => {
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    const cfg = { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, min_samples: 5 };
+    for (let i = 0; i < 250; i++) {
+      applyCac(result, {
+        config: cfg,
+        historyProvider: () => ({ adopted: 1, total: 100 }),
+        severityProvider: () => ({ adopted: 0, total: 0 }),
+        filePath: `app/views/pages/p${i}.liquid`,
+      });
+    }
+    const recorded = getRecentCacDecisions();
+    expect(recorded.length).toBeLessThanOrEqual(200);
+    expect(recorded.at(-1).file).toContain('p249');
+  });
+
+  test('emits cac_decision events to sessionBus when provided', () => {
+    const events = [];
+    const sessionBus = { emit: (kind, payload, ts) => events.push({ kind, payload, ts }) };
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, min_samples: 5 },
+      historyProvider: () => ({ adopted: 1, total: 100 }),
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      sessionBus,
+      filePath: 'app/views/pages/p.liquid',
+    });
+    expect(events).toHaveLength(1);
+    expect(events[0].kind).toBe('cac_decision');
+    expect(events[0].payload.decision).toBe('downgrade');
+    // Regression: the payload MUST NOT carry a `ts` field — that key is
+    // reserved by the session-bus envelope (ENVELOPE_KEYS in
+    // session-events.js). When it slipped through, makeEvent threw and the
+    // try/catch in recordDecision dropped the event silently. The bus arg
+    // is the timestamp's only home.
+    expect(events[0].payload.ts).toBeUndefined();
+    expect(typeof events[0].ts).toBe('string');
+    expect(events[0].ts).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test('emit failure does not break the in-memory ring', () => {
+    // The session bus may throw on its own (writer closed, fsync error,
+    // misconfigured kind). The predictor's audit trail in memory is the
+    // dashboard's primary source within a session — it must survive.
+    const sessionBus = {
+      emit: () => { throw new Error('writer closed'); },
+    };
+    const result = makeResult([
+      { severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' },
+    ]);
+    expect(() => applyCac(result, {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, min_samples: 5 },
+      historyProvider: () => ({ adopted: 1, total: 100 }),
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      sessionBus,
+      filePath: 'app/views/pages/p.liquid',
+    })).not.toThrow();
+    expect(getRecentCacDecisions()).toHaveLength(1);
+  });
+});
+
+// ── loadRecentCacDecisions / rehydrateRecentCacDecisions ─────────────────────
+
+const SID = 'session-2026-04-29T00-00-00-000Z';
+
+function writeSessionLog(dir, sessionName, events) {
+  const sessionDir = join(dir, sessionName);
+  mkdirSync(sessionDir, { recursive: true });
+  const lines = events.map(e => JSON.stringify(e)).join('\n') + '\n';
+  writeFileSync(join(sessionDir, 'events.ndjson'), lines, 'utf8');
+}
+
+function cacDecisionEvent({ session = SID, ts, ...payload }) {
+  return makeEvent({
+    session_id: session,
+    ts,
+    kind: 'cac_decision',
+    payload: {
+      file: 'app/views/pages/p.liquid',
+      rule_id: 'X.y',
+      check: 'X',
+      severity: 'warning',
+      file_domain: 'pages',
+      p_adopted: 0.18,
+      p_lower: 0.05,
+      p_upper: 0.45,
+      n_samples: 7,
+      feature: 'rule_id',
+      decision: 'downgrade',
+      reason: 'below_threshold',
+      mode: 'shadow',
+      ...payload,
+    },
+  });
+}
+
+describe('loadRecentCacDecisions', () => {
+  let dir;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'cac-load-'));
+  });
+
+  test('returns [] when sessions dir is missing', () => {
+    expect(loadRecentCacDecisions(join(dir, 'absent'))).toEqual([]);
+  });
+
+  test('returns [] when sessions dir is empty', () => {
+    mkdirSync(join(dir, 'sessions'));
+    expect(loadRecentCacDecisions(join(dir, 'sessions'))).toEqual([]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('reads cac_decision events from one session and returns ring-shape entries', () => {
+    const events = [
+      cacDecisionEvent({ ts: '2026-04-29T01:00:00.000Z', file: 'a.liquid', rule_id: 'A.x' }),
+      cacDecisionEvent({ ts: '2026-04-29T01:00:01.000Z', file: 'b.liquid', rule_id: 'B.y' }),
+    ];
+    writeSessionLog(dir, SID, events);
+
+    const out = loadRecentCacDecisions(dir);
+    expect(out).toHaveLength(2);
+    expect(out[0].ts).toBe('2026-04-29T01:00:00.000Z');
+    expect(out[0].file).toBe('a.liquid');
+    expect(out[0].rule_id).toBe('A.x');
+    // Ring shape: ts is on the entry, payload fields are flattened
+    expect(out[1].decision).toBe('downgrade');
+    expect(out[1].feature).toBe('rule_id');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('skips non-cac_decision lines without crashing', () => {
+    const mixed = [
+      makeEvent({ session_id: SID, ts: '2026-04-29T01:00:00.000Z', kind: 'server_start',
+        payload: { project_dir: '/x', version: '0.0.0', started_at: '2026-04-29T01:00:00.000Z' } }),
+      cacDecisionEvent({ ts: '2026-04-29T01:00:01.000Z' }),
+      makeEvent({ session_id: SID, ts: '2026-04-29T01:00:02.000Z', kind: 'log',
+        payload: { level: 'info', message: 'hi' } }),
+    ];
+    writeSessionLog(dir, SID, mixed);
+
+    const out = loadRecentCacDecisions(dir);
+    expect(out).toHaveLength(1);
+    expect(out[0].ts).toBe('2026-04-29T01:00:01.000Z');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('tolerates malformed JSON lines and partial events', () => {
+    const valid = cacDecisionEvent({ ts: '2026-04-29T01:00:00.000Z' });
+    const sessionDir = join(dir, SID);
+    mkdirSync(sessionDir, { recursive: true });
+    const content = [
+      '{not-json',
+      JSON.stringify(valid),
+      '',
+      '{"v":1,"session_id":"x","ts":"2026-04-29T01:00:00.000Z","kind":"cac_decision"}', // missing payload fields
+      '{"v":99,"kind":"cac_decision"}', // unsupported version
+    ].join('\n');
+    writeSessionLog(dir, SID, []); // ensure dir exists; we then overwrite the file
+    writeFileSync(join(sessionDir, 'events.ndjson'), content, 'utf8');
+
+    const out = loadRecentCacDecisions(dir);
+    expect(out).toHaveLength(1);
+    expect(out[0].ts).toBe('2026-04-29T01:00:00.000Z');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('merges decisions across multiple sessions in chronological order', () => {
+    writeSessionLog(dir, 'session-2026-04-28T00-00-00-000Z', [
+      cacDecisionEvent({ session: 'session-2026-04-28T00-00-00-000Z',
+        ts: '2026-04-28T01:00:00.000Z', file: 'old.liquid' }),
+    ]);
+    writeSessionLog(dir, 'session-2026-04-29T00-00-00-000Z', [
+      cacDecisionEvent({ session: 'session-2026-04-29T00-00-00-000Z',
+        ts: '2026-04-29T01:00:00.000Z', file: 'new.liquid' }),
+    ]);
+
+    const out = loadRecentCacDecisions(dir);
+    expect(out).toHaveLength(2);
+    expect(out[0].file).toBe('old.liquid');
+    expect(out[1].file).toBe('new.liquid');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('respects the limit, keeping the most recent entries', () => {
+    const events = [];
+    for (let i = 0; i < 50; i++) {
+      const tsMs = Date.UTC(2026, 3, 29, 1, 0, i, 0); // sequential second granularity
+      events.push(cacDecisionEvent({
+        ts: new Date(tsMs).toISOString(),
+        file: `f${i}.liquid`,
+      }));
+    }
+    writeSessionLog(dir, SID, events);
+
+    const out = loadRecentCacDecisions(dir, 10);
+    expect(out).toHaveLength(10);
+    // Most recent kept, oldest dropped
+    expect(out[0].file).toBe('f40.liquid');
+    expect(out[9].file).toBe('f49.liquid');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('limit <= 0 returns empty without I/O', () => {
+    expect(loadRecentCacDecisions(dir, 0)).toEqual([]);
+    expect(loadRecentCacDecisions(dir, -5)).toEqual([]);
+  });
+});
+
+describe('rehydrateRecentCacDecisions', () => {
+  let dir;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'cac-rehydrate-'));
+    clearRecentCacDecisions();
+  });
+
+  test('replaces the in-memory ring with decisions from disk', () => {
+    writeSessionLog(dir, SID, [
+      cacDecisionEvent({ ts: '2026-04-29T01:00:00.000Z', file: 'a.liquid' }),
+      cacDecisionEvent({ ts: '2026-04-29T01:00:01.000Z', file: 'b.liquid' }),
+    ]);
+
+    const n = rehydrateRecentCacDecisions(dir);
+    expect(n).toBe(2);
+    const ring = getRecentCacDecisions();
+    expect(ring).toHaveLength(2);
+    expect(ring[0].file).toBe('a.liquid');
+    expect(ring[1].file).toBe('b.liquid');
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('is idempotent — repeated calls produce the same ring', () => {
+    writeSessionLog(dir, SID, [
+      cacDecisionEvent({ ts: '2026-04-29T01:00:00.000Z' }),
+    ]);
+    rehydrateRecentCacDecisions(dir);
+    rehydrateRecentCacDecisions(dir);
+    expect(getRecentCacDecisions()).toHaveLength(1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('clears the ring when the sessions dir is empty (no carry-over)', () => {
+    // Pre-seed via a live emit so the ring has content
+    applyCac(makeResult([{ severity: 'error', check: 'X', rule_id: 'X.bad', message: 'a' }]), {
+      config: { ...defaultCacConfig(), enabled: true, mode: 'shadow', threshold: 0.5, min_samples: 5 },
+      historyProvider: () => ({ adopted: 1, total: 100 }),
+      severityProvider: () => ({ adopted: 0, total: 0 }),
+      filePath: 'app/views/pages/p.liquid',
+    });
+    expect(getRecentCacDecisions().length).toBeGreaterThan(0);
+
+    rehydrateRecentCacDecisions(dir);
+    expect(getRecentCacDecisions()).toHaveLength(0);
+  });
+
+  test('handles missing sessions dir without throwing', () => {
+    expect(() => rehydrateRecentCacDecisions(join(dir, 'never-existed'))).not.toThrow();
+    expect(getRecentCacDecisions()).toHaveLength(0);
+  });
+});
diff --git a/tests/unit/diagnostic-pipeline.test.js b/tests/unit/diagnostic-pipeline.test.js
index 53e6726..9526fee 100644
--- a/tests/unit/diagnostic-pipeline.test.js
+++ b/tests/unit/diagnostic-pipeline.test.js
@@ -248,6 +248,79 @@ describe('diagnostic-pipeline: pending suppression via runDiagnosticPipeline', (
   });
 });
 
+// ── verifyMissingPartialsOnDisk: lib/-prefix correctness ────────────────────
+//
+// Regression: the resolver used to strip a leading `lib/` before the disk
+// check, which routed `lib/commands/X` to `app/lib/commands/X.liquid` and
+// silently suppressed the LSP's correct MissingPartial when that bare-form
+// file existed. Net effect: the agent saw "no problem" while platformOS
+// would 500 at runtime because `lib/commands/X` resolves to
+// `app/lib/lib/commands/X.liquid` (the partial search paths are
+// `app/views/partials/` and `app/lib/`, not project root). The resolver
+// now mirrors upstream `DocumentsLocator` exactly — no prefix stripping —
+// so the LSP error survives all the way to the agent.
+
+describe('diagnostic-pipeline: verifyMissingPartialsOnDisk does not strip `lib/` prefix', () => {
+  let tmpDir;
+
+  beforeAll(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'pipeline-libpref-'));
+    mkdirSync(join(tmpDir, 'app/lib/commands/contacts'), { recursive: true });
+    writeFileSync(
+      join(tmpDir, 'app/lib/commands/contacts/create.liquid'),
+      '{% doc %}{% enddoc %}',
+      'utf8',
+    );
+    mkdirSync(join(tmpDir, 'app/views/partials/cards'), { recursive: true });
+    writeFileSync(
+      join(tmpDir, 'app/views/partials/cards/product.liquid'),
+      '
        ',
+      'utf8',
+    );
+  });
+
+  afterAll(() => { if (tmpDir) rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('suppresses MissingPartial for the bare `commands/X` form when X.liquid is on disk (LSP cache lag)', () => {
+    const result = makeResult([
+      { check: 'MissingPartial', severity: 'error', message: "'commands/contacts/create' does not exist" },
+    ]);
+    runDiagnosticPipeline(result, { filePath: 'app/views/pages/contacts/new.html.liquid', content: '', projectDir: tmpDir });
+    expect(result.errors).toHaveLength(0);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:MissingPartialSuppressed')).toBe(true);
+  });
+
+  it('does NOT suppress MissingPartial for the `lib/commands/X` form — the `lib/` prefix expands to `app/lib/lib/...`', () => {
+    const result = makeResult([
+      { check: 'MissingPartial', severity: 'error', message: "'lib/commands/contacts/create' does not exist" },
+    ]);
+    runDiagnosticPipeline(result, { filePath: 'app/views/pages/contacts/new.html.liquid', content: '', projectDir: tmpDir });
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].message).toContain('lib/commands/contacts/create');
+    expect(result.infos.some(i => i.check === 'pos-supervisor:MissingPartialSuppressed')).toBe(false);
+  });
+
+  it('does NOT suppress MissingPartial for the `lib/queries/X` form even when the bare-form file exists on disk', () => {
+    mkdirSync(join(tmpDir, 'app/lib/queries/products'), { recursive: true });
+    writeFileSync(join(tmpDir, 'app/lib/queries/products/find.liquid'), '{% doc %}{% enddoc %}', 'utf8');
+    const result = makeResult([
+      { check: 'MissingPartial', severity: 'error', message: "'lib/queries/products/find' does not exist" },
+    ]);
+    runDiagnosticPipeline(result, { filePath: 'app/views/pages/products/show.html.liquid', content: '', projectDir: tmpDir });
+    expect(result.errors).toHaveLength(1);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:MissingPartialSuppressed')).toBe(false);
+  });
+
+  it('still suppresses real partial cache-lag misses (non-`lib/` paths)', () => {
+    const result = makeResult([
+      { check: 'MissingPartial', severity: 'error', message: "'cards/product' does not exist" },
+    ]);
+    runDiagnosticPipeline(result, { filePath: 'app/views/pages/index.html.liquid', content: '', projectDir: tmpDir });
+    expect(result.errors).toHaveLength(0);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:MissingPartialSuppressed')).toBe(true);
+  });
+});
+
 // ── verifyMissingAssets ──────────────────────────────────────────────────────
 
 describe('diagnostic-pipeline: verifyMissingAssets via runDiagnosticPipeline', () => {
diff --git a/tests/unit/error-enricher.test.js b/tests/unit/error-enricher.test.js
index 162f1c3..aa3b1c0 100644
--- a/tests/unit/error-enricher.test.js
+++ b/tests/unit/error-enricher.test.js
@@ -97,13 +97,13 @@ describe('MissingPartial hint template resolution', () => {
     const diagnostic = {
       check: 'MissingPartial',
       severity: 'error',
-      message: "Missing partial 'lib/commands/products/create'",
+      message: "Missing partial 'commands/products/create'",
       line: 3,
       column: 3,
     };
     const result = await enrichError(diagnostic, {
       uri: 'file:///app/views/pages/test.html.liquid',
-      content: "---\nslug: test\n---\n{% function result = 'lib/commands/products/create', params: context.params %}",
+      content: "---\nslug: test\n---\n{% function result = 'commands/products/create', params: context.params %}",
     });
 
     expect(result.hint).toContain('command');
@@ -116,13 +116,13 @@ describe('MissingPartial hint template resolution', () => {
     const diagnostic = {
       check: 'MissingPartial',
       severity: 'error',
-      message: "Missing partial 'lib/queries/products/search'",
+      message: "Missing partial 'queries/products/search'",
       line: 3,
       column: 3,
     };
     const result = await enrichError(diagnostic, {
       uri: 'file:///app/views/pages/test.html.liquid',
-      content: "---\nslug: test\n---\n{% function result = 'lib/queries/products/search', query_params: context.params %}",
+      content: "---\nslug: test\n---\n{% function result = 'queries/products/search', query_params: context.params %}",
     });
 
     expect(result.hint).toContain('query');
@@ -131,6 +131,38 @@ describe('MissingPartial hint template resolution', () => {
     expect(result.hint).not.toContain('{{');
   });
 
+  it('flags `lib/` prefix as invalid and points at the corrected path', async () => {
+    // Regression: the `lib/commands/X` and `lib/queries/X` forms used to be
+    // accepted as valid call forms in our hints/data — they aren't. The
+    // upstream resolver searches `app/views/partials/` and `app/lib/`, so a
+    // literal `lib/` prefix expands to `app/lib/lib/...` and never resolves.
+    // The enricher must surface this distinctly, with the corrected path
+    // (no phantom `app/lib/lib/...`) and a "drop the prefix" message —
+    // never a "create the file" message.
+    const diagnostic = {
+      check: 'MissingPartial',
+      severity: 'error',
+      message: "'lib/commands/products/create' does not exist",
+      line: 3,
+      column: 3,
+    };
+    const result = await enrichError(diagnostic, {
+      uri: 'file:///app/views/pages/test.html.liquid',
+      content: "---\nslug: test\n---\n{% function result = 'lib/commands/products/create', params: context.params %}",
+    });
+
+    expect(result.hint).toContain('lib/commands/products/create');
+    expect(result.hint).toContain('commands/products/create');
+    // Corrected disk path — the single-`lib/` resolution
+    expect(result.hint).toContain('app/lib/commands/products/create.liquid');
+    // Variant must not be the create-file template — the issue is the path
+    // syntax, not a missing file
+    expect(result.hint).not.toMatch(/STEP 2 — Create/);
+    // Hint must call out the prefix as invalid (the fix is to drop it)
+    expect(result.hint).toMatch(/lib\/[^\s]+ is not a valid path|drop the `lib\/` prefix/i);
+    expect(result.hint).not.toContain('{{');
+  });
+
   it('uses module variant hint for module paths — references project_map, no create path', async () => {
     const diagnostic = {
       check: 'MissingPartial',
diff --git a/tests/unit/rules/MissingPartial.test.js b/tests/unit/rules/MissingPartial.test.js
index aba76ac..732077c 100644
--- a/tests/unit/rules/MissingPartial.test.js
+++ b/tests/unit/rules/MissingPartial.test.js
@@ -215,6 +215,115 @@ describe('MissingPartial.create_file', () => {
   });
 });
 
+describe('MissingPartial.invalid_lib_prefix', () => {
+  // Regression: prior code stripped a leading `lib/` everywhere it saw one,
+  // collapsing `lib/commands/X` and `commands/X` into the same bucket. That
+  // hid the bug from agents (and from us) — `lib/commands/X` is *not* a
+  // valid platformOS function-tag path, since paths resolve under
+  // `app/views/partials/` and `app/lib/`. The literal prefix expands to
+  // `app/lib/lib/...` and never resolves.
+
+  test('fires for `lib/commands/X` with the corrected name in the hint', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/commands/contact_submissions/create' },
+      line: 6,
+      column: 20,
+      endLine: 6,
+      endColumn: 61,
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.invalid_lib_prefix');
+    expect(result.hint_md).toContain('lib/commands/contact_submissions/create');
+    expect(result.hint_md).toContain('commands/contact_submissions/create');
+    expect(result.confidence).toBeGreaterThanOrEqual(0.9);
+  });
+
+  test('emits a text_edit fix that replaces the quoted reference with the corrected form', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/commands/contact_submissions/create' },
+      line: 6,
+      column: 20,
+      endLine: 6,
+      endColumn: 61,
+    };
+    const result = runRules(diag, facts);
+    expect(result.fixes).toHaveLength(1);
+    const fix = result.fixes[0];
+    expect(fix.type).toBe('text_edit');
+    expect(fix.new_text).toBe(`'commands/contact_submissions/create'`);
+    expect(fix.range).toEqual({
+      start: { line: 6, character: 20 },
+      end:   { line: 6, character: 61 },
+    });
+  });
+
+  test('falls back to a guidance fix when the diagnostic lacks position fields', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/queries/products/search' },
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.invalid_lib_prefix');
+    expect(result.fixes).toHaveLength(1);
+    expect(result.fixes[0].type).toBe('guidance');
+    expect(result.fixes[0].description).toContain('lib/queries/products/search');
+    expect(result.fixes[0].description).toContain('queries/products/search');
+  });
+
+  test('handles `lib/queries/X` symmetrically with `lib/commands/X`', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/queries/products/search' },
+      line: 4,
+      column: 16,
+      endLine: 4,
+      endColumn: 47,
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.invalid_lib_prefix');
+    expect(result.fixes[0].type).toBe('text_edit');
+    expect(result.fixes[0].new_text).toBe(`'queries/products/search'`);
+  });
+
+  test('does NOT fire for the bare `commands/X` form (the canonical syntax)', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'commands/contact_submissions/create' },
+      line: 1, column: 0, endLine: 1, endColumn: 35,
+    };
+    const result = runRules(diag, facts);
+    expect(result?.rule_id).not.toBe('MissingPartial.invalid_lib_prefix');
+  });
+
+  test('does NOT fire for module paths that happen to contain `lib/`', () => {
+    // Module paths look like `modules/core/lib/commands/...` in some tree
+    // layouts on disk, but the *call* path is `modules//...` — never
+    // begins with `lib/`. Guard against false positives.
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'modules/core/commands/execute' },
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+  });
+
+  test('beats lower-priority rules: invalid_lib_prefix wins over create_file even when the corrected file would not exist', () => {
+    // The `lib/`-stripped path `commands/never/written` resolves to
+    // `app/lib/commands/never/written.liquid` — absent from the fact graph.
+    // create_file would happily propose creating it; the prefix rule must
+    // fire first so the agent is told to fix the path, not create a phantom.
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/commands/never/written' },
+      line: 2, column: 10, endLine: 2, endColumn: 39,
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.invalid_lib_prefix');
+  });
+});
+
 describe('MissingPartial — edge cases', () => {
   test('returns null when partial param is missing', () => {
     const diag = { check: 'MissingPartial', params: {} };
diff --git a/tests/unit/rules/queries.test.js b/tests/unit/rules/queries.test.js
index ae965dd..90a54a4 100644
--- a/tests/unit/rules/queries.test.js
+++ b/tests/unit/rules/queries.test.js
@@ -172,14 +172,30 @@ describe('classifyPath', () => {
     expect(classifyPath('commands/blog_posts/create')).toEqual({ type: 'command', path: 'app/lib/commands/blog_posts/create.liquid' });
   });
 
-  test('classifies lib/commands prefix', () => {
-    expect(classifyPath('lib/commands/blog_posts/create')).toEqual({ type: 'command', path: 'app/lib/commands/blog_posts/create.liquid' });
+  test('flags `lib/commands/` as an invalid prefix and exposes the corrected name', () => {
+    // Function-tag paths resolve under the partial search paths
+    // (`app/views/partials/`, `app/lib/`), so a literal `lib/` prefix
+    // would expand to `app/lib/lib/...` which never exists. Treating the
+    // prefix as "optional" (the prior behaviour) hid the bug from agents.
+    expect(classifyPath('lib/commands/blog_posts/create')).toEqual({
+      type: 'invalid_lib_prefix',
+      path: null,
+      correctedName: 'commands/blog_posts/create',
+    });
   });
 
   test('classifies query', () => {
     expect(classifyPath('queries/blog_posts/find')).toEqual({ type: 'query', path: 'app/lib/queries/blog_posts/find.liquid' });
   });
 
+  test('flags `lib/queries/` as an invalid prefix and exposes the corrected name', () => {
+    expect(classifyPath('lib/queries/blog_posts/find')).toEqual({
+      type: 'invalid_lib_prefix',
+      path: null,
+      correctedName: 'queries/blog_posts/find',
+    });
+  });
+
   test('classifies module', () => {
     expect(classifyPath('modules/user/helpers/auth')).toEqual({ type: 'module', path: null });
   });
diff --git a/tests/unit/session-events.test.js b/tests/unit/session-events.test.js
index 8f45f4c..f687275 100644
--- a/tests/unit/session-events.test.js
+++ b/tests/unit/session-events.test.js
@@ -43,6 +43,7 @@ describe('session-events: schema registry', () => {
       'tool_call',
       'validator_emit',
       'log',
+      'cac_decision',
     ]);
     for (const kind of KNOWN_KINDS) {
       expect(KIND_SCHEMAS[kind]).toBeDefined();
@@ -111,6 +112,107 @@ describe('session-events: makeEvent + validateEvent', () => {
     expect(e.input.anything.nested).toBe(true);
     expect(e.output.warnings[0].check).toBe('X');
   });
+
+  // Regression: prior to registering the schema, every cac_decision emit
+  // threw "unknown kind" inside makeEvent, the throw was swallowed by the
+  // caller's try/catch, and the predictor's audit trail was silently lost
+  // on every restart. Pin the happy path AND every rejection edge so a
+  // future refactor can't reopen the hole quietly.
+  it('builds a cac_decision event with envelope + payload', () => {
+    const e = makeEvent({
+      session_id: SID, ts: FIXED_TS, kind: 'cac_decision',
+      payload: {
+        file: 'app/views/pages/index.liquid',
+        rule_id: 'MissingPartial.create_file',
+        check: 'MissingPartial',
+        severity: 'error',
+        file_domain: 'pages',
+        p_adopted: 0.18,
+        p_lower: 0.05,
+        p_upper: 0.45,
+        n_samples: 7,
+        feature: 'rule_id',
+        decision: 'downgrade',
+        reason: 'below_threshold',
+        mode: 'shadow',
+      },
+    });
+    expect(e.kind).toBe('cac_decision');
+    expect(e.rule_id).toBe('MissingPartial.create_file');
+    expect(e.feature).toBe('rule_id');
+    expect(e.decision).toBe('downgrade');
+    expect(e.mode).toBe('shadow');
+  });
+
+  it('cac_decision accepts the no-signal `prior` shape with null probabilities', () => {
+    const e = makeEvent({
+      session_id: SID, ts: FIXED_TS, kind: 'cac_decision',
+      payload: {
+        file: 'app/views/pages/x.liquid',
+        rule_id: 'NewCheck.unmatched',
+        check: 'NewCheck',
+        severity: 'warning',
+        file_domain: null,
+        p_adopted: 0.5,
+        p_lower: null,
+        p_upper: null,
+        n_samples: 0,
+        feature: 'prior',
+        decision: 'allow',
+        reason: 'no_signal',
+        mode: 'shadow',
+      },
+    });
+    expect(e.feature).toBe('prior');
+    expect(e.p_lower).toBeNull();
+  });
+
+  it('cac_decision rejects a payload that smuggles the envelope `ts` key', () => {
+    // This is the exact collision that used to drop events at runtime — the
+    // ring entry carried `ts` (its own timestamp) and was passed verbatim
+    // as a payload, hitting `ENVELOPE_KEYS` in makeEvent.
+    expect(() => makeEvent({
+      session_id: SID, ts: FIXED_TS, kind: 'cac_decision',
+      payload: {
+        ts: FIXED_TS,
+        rule_id: 'X', severity: 'error',
+        p_adopted: 0.5, p_lower: null, p_upper: null,
+        n_samples: 0, feature: 'prior', decision: 'allow', reason: '',
+        mode: 'shadow',
+      },
+    })).toThrow(/reserved envelope key/i);
+  });
+
+  it('cac_decision rejects an unknown decision value', () => {
+    expect(() => makeEvent({
+      session_id: SID, ts: FIXED_TS, kind: 'cac_decision',
+      payload: {
+        rule_id: 'X', severity: 'error',
+        p_adopted: 0.5, p_lower: null, p_upper: null,
+        n_samples: 0, feature: 'prior', decision: 'mute_forever', reason: '',
+        mode: 'shadow',
+      },
+    })).toThrow();
+  });
+
+  it('cac_decision round-trips through readEvent / writeEvent', () => {
+    const written = makeEvent({
+      session_id: SID, ts: FIXED_TS, kind: 'cac_decision',
+      payload: {
+        file: 'a.liquid',
+        rule_id: 'PartialCallArguments.required_render',
+        check: 'PartialCallArguments',
+        severity: 'warning',
+        file_domain: 'partials',
+        p_adopted: 0.17, p_lower: 0.03, p_upper: 0.41,
+        n_samples: 8, feature: 'rule_id+domain',
+        decision: 'downgrade', reason: 'below_threshold',
+        mode: 'active',
+      },
+    });
+    const back = readEvent(JSON.stringify(written));
+    expect(back).toEqual(written);
+  });
 });
 
 describe('session-events: readEvent', () => {

From e8fa5626f7b6ba93af9143bf0cadc3252a29f697 Mon Sep 17 00:00:00 2001
From: Filip Klosowski 
Date: Thu, 30 Apr 2026 12:34:06 +0200
Subject: [PATCH 19/20] Removed serena

---
 .serena/.gitignore  |   2 -
 .serena/project.yml | 127 --------------------------------------------
 2 files changed, 129 deletions(-)
 delete mode 100644 .serena/.gitignore
 delete mode 100644 .serena/project.yml

diff --git a/.serena/.gitignore b/.serena/.gitignore
deleted file mode 100644
index 2e510af..0000000
--- a/.serena/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-/cache
-/project.local.yml
diff --git a/.serena/project.yml b/.serena/project.yml
deleted file mode 100644
index 671f431..0000000
--- a/.serena/project.yml
+++ /dev/null
@@ -1,127 +0,0 @@
-# the name by which the project can be referenced within Serena
-project_name: "pos-mcp"
-
-
-# list of languages for which language servers are started; choose from:
-#   al                  ansible             bash                clojure             cpp
-#   cpp_ccls            crystal             csharp              csharp_omnisharp    dart
-#   elixir              elm                 erlang              fortran             fsharp
-#   go                  groovy              haskell             haxe                hlsl
-#   java                json                julia               kotlin              lean4
-#   lua                 luau                markdown            matlab              msl
-#   nix                 ocaml               pascal              perl                php
-#   php_phpactor        powershell          python              python_jedi         python_ty
-#   r                   rego                ruby                ruby_solargraph     rust
-#   scala               solidity            swift               systemverilog       terraform
-#   toml                typescript          typescript_vts      vue                 yaml
-#   zig
-#   (This list may be outdated. For the current list, see values of Language enum here:
-#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
-#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
-# Note:
-#   - For C, use cpp
-#   - For JavaScript, use typescript
-#   - For Free Pascal/Lazarus, use pascal
-# Special requirements:
-#   Some languages require additional setup/installations.
-#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
-# When using multiple languages, the first language server that supports a given file will be used for that file.
-# The first language is the default language and the respective language server will be used as a fallback.
-# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
-languages:
-- typescript
-
-# the encoding used by text files in the project
-# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
-encoding: "utf-8"
-
-# line ending convention to use when writing source files.
-# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
-# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
-line_ending:
-
-# The language backend to use for this project.
-# If not set, the global setting from serena_config.yml is used.
-# Valid values: LSP, JetBrains
-# Note: the backend is fixed at startup. If a project with a different backend
-# is activated post-init, an error will be returned.
-language_backend:
-
-# whether to use project's .gitignore files to ignore files
-ignore_all_files_in_gitignore: true
-
-# advanced configuration option allowing to configure language server-specific options.
-# Maps the language key to the options.
-# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
-# No documentation on options means no options are available.
-ls_specific_settings: {}
-
-# list of additional paths to ignore in this project.
-# Same syntax as gitignore, so you can use * and **.
-# Note: global ignored_paths from serena_config.yml are also applied additively.
-ignored_paths: []
-
-# whether the project is in read-only mode
-# If set to true, all editing tools will be disabled and attempts to use them will result in an error
-# Added on 2025-04-18
-read_only: false
-
-# list of tool names to exclude.
-# This extends the existing exclusions (e.g. from the global configuration)
-# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
-excluded_tools: []
-
-# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
-# This extends the existing inclusions (e.g. from the global configuration).
-# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
-included_optional_tools: []
-
-# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
-# This cannot be combined with non-empty excluded_tools or included_optional_tools.
-# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
-fixed_tools: []
-
-# list of mode names to that are always to be included in the set of active modes
-# The full set of modes to be activated is base_modes + default_modes.
-# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
-# Otherwise, this setting overrides the global configuration.
-# Set this to [] to disable base modes for this project.
-# Set this to a list of mode names to always include the respective modes for this project.
-base_modes:
-
-# list of mode names that are to be activated by default, overriding the setting in the global configuration.
-# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
-# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
-# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
-# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
-# for this project.
-# This setting can, in turn, be overridden by CLI parameters (--mode).
-# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
-default_modes:
-
-# initial prompt for the project. It will always be given to the LLM upon activating the project
-# (contrary to the memories, which are loaded on demand).
-initial_prompt: ""
-
-# time budget (seconds) per tool call for the retrieval of additional symbol information
-# such as docstrings or parameter information.
-# This overrides the corresponding setting in the global configuration; see the documentation there.
-# If null or missing, use the setting from the global configuration.
-symbol_info_budget:
-
-# list of regex patterns which, when matched, mark a memory entry as read‑only.
-# Extends the list from the global configuration, merging the two lists.
-read_only_memory_patterns: []
-
-# list of regex patterns for memories to completely ignore.
-# Matching memories will not appear in list_memories or activate_project output
-# and cannot be accessed via read_memory or write_memory.
-# To access ignored memory files, use the read_file tool on the raw file path.
-# Extends the list from the global configuration, merging the two lists.
-# Example: ["_archive/.*", "_episodes/.*"]
-ignored_memory_patterns: []
-
-# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
-# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
-# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
-added_modes:

From 453ed3ffd3025578b683a9b7dd67f2fcb8dccbf3 Mon Sep 17 00:00:00 2001
From: Filip Klosowski 
Date: Fri, 1 May 2026 23:29:01 +0200
Subject: [PATCH 20/20] WIP

---
 CHANGELOG.md                                  | 124 +++
 SYSTEM_ARCHITECTURE.md                        | 945 ++++++++++++++++++
 package.json                                  |   2 +-
 src/core/analytics-labels.js                  | 126 +++
 src/core/analytics-queries.js                 | 293 ++++--
 src/core/analytics-store.js                   |  50 +
 src/core/case-base.js                         | 136 ++-
 src/core/diagnostic-pipeline.js               |  98 +-
 src/core/page-route-index.js                  |  52 +-
 src/core/rules/MissingPartial.js              |  47 +
 src/core/rules/TranslationKeyExists.js        |  55 +-
 src/core/rules/UndefinedObject.js             |  42 +-
 src/core/rules/UnknownFilter.js               |  43 +-
 src/core/rules/UnknownProperty.js             |  41 +-
 src/dashboard.js                              | 236 ++++-
 src/http-server.js                            | 244 +++--
 src/server.js                                 |   7 +-
 src/tools/server-status.js                    |   6 +-
 tests/unit/analytics-labels.test.js           | 234 +++++
 tests/unit/analytics-queries.test.js          | 299 ++++++
 tests/unit/analytics-store.test.js            |  79 ++
 tests/unit/case-base.test.js                  | 173 +++-
 tests/unit/diagnostic-pipeline.test.js        | 245 +++++
 tests/unit/http-handler-arity.test.js         | 158 +++
 tests/unit/http-since-param.test.js           |  63 ++
 tests/unit/page-route-index.test.js           |  87 ++
 tests/unit/rules/MissingPartial.test.js       |  61 +-
 tests/unit/rules/TranslationKeyExists.test.js |  46 +-
 tests/unit/rules/UndefinedObject.test.js      |  48 +-
 tests/unit/rules/UnknownFilter.test.js        |  53 +-
 tests/unit/unknown-property-rules.test.js     |  78 +-
 31 files changed, 3928 insertions(+), 243 deletions(-)
 create mode 100644 SYSTEM_ARCHITECTURE.md
 create mode 100644 src/core/analytics-labels.js
 create mode 100644 tests/unit/analytics-labels.test.js
 create mode 100644 tests/unit/http-handler-arity.test.js
 create mode 100644 tests/unit/http-since-param.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index baa1c3a..13e4c36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,129 @@
 # Changelog
 
+## 0.7.3 — 2026-04-30
+
+Reporting baseline + sample-size-gated labels — operator-set checkpoint
+that filters every dashboard widget and exported Markdown report by a
+chosen "stats since" timestamp, plus a presentation-layer label gate
+that replaces nonsense `AT RISK -100%` / `HARMFUL` headlines on N<5
+samples with `INSUFFICIENT_DATA`. Engine state (auto-disable, case-base
+scoring, CAC predictor, adaptive-mode probation) is **never** baselined
+— it always sees full history. Default behaviour with no baseline set
+is identical to 0.7.2.
+
+### Added — `src/core/analytics-store.js` baseline helpers
+
+Two new meta keys (`analytics_baseline_ts`, `analytics_baseline_set_at`)
+plus four helpers: `getBaselineTs()`, `getBaselineMeta()`,
+`setBaselineTs(iso | null)`, `clearBaseline()`. Stored in the existing
+`meta` table — no schema migration. `setBaselineTs` validates ISO input
+and rejects malformed strings with `TypeError` so the HTTP layer can
+return 400 cleanly. The baseline survives `rebuild()` (rebuild only
+clears derived data, not meta).
+
+### Added — `src/core/analytics-labels.js`
+
+Pure, side-effect-free presentation module owning the GOOD / OK / LOW /
+HARMFUL, AT RISK / UNMATCHED, and INSUFFICIENT_DATA labels. The
+`LABEL_MIN_OUTCOMES = 5` gate is the load-bearing change: a rule with a
+single regression no longer headlines as AT RISK -100%, it lands in
+INSUFFICIENT_DATA. Exports `checkLabel`, `ruleLabel`, `harmfulSummary`,
+`withCheckLabels`, `withRuleLabels`. The HTTP layer wraps every
+scorecard / rule-performance response with `withCheckLabels` /
+`withRuleLabels` so the dashboard reads `.label` directly without
+recomputing client-side. Inline label calculations in dashboard.js are
+preserved as fallbacks for un-labelled responses.
+
+### Added — `since` parameter across reporting queries
+
+Tri-state contract on every reporting query in
+`src/core/analytics-queries.js` (`checkScorecards`, `rulePerformance`,
+`fixRulePerformance`, `fixAdoptionFunnel`, `knowledgeGaps`,
+`confidenceCalibration`, `ruleScoresByCategory`, `sessionSummaries`,
+`toolSequenceBigrams`, `diagnosticJourney`, `ruleDrilldown`,
+`recommendations`) and the reporting paths in `src/core/case-base.js`
+(`retrieveCases`, `retrieveCasesByCheck`, `ruleScores`, `suggestedRules`,
+`synthesizeGuardPredicate`):
+
+- `since: undefined` → reads the operator-set baseline from
+  `meta.analytics_baseline_ts`. Absent meta ⇒ no filter ⇒ full history.
+  This is the dashboard / report default.
+- `since: null` → explicit bypass. Reserved for engine-state callers
+  that must see full history regardless of baseline.
+  `server.js:syncDisabledRules` and `tools/server-status.js` were
+  updated to pass this. `scoreRule` and `cac-predictor` providers and
+  `resolveProbation` keep no `since` parameter at all — they cannot
+  accept a baseline argument by design.
+- `since: ''` → explicit override. Used by the dashboard's "Stats
+  since" dropdown for 24h / 7d / custom selections.
+
+### Added — HTTP endpoints + `?since=` parameter
+
+Two new endpoints on `src/http-server.js`:
+
+- `GET /api/analytics/baseline` → `{ baseline_ts, set_at }`.
+- `POST /api/analytics/baseline` body `{ baseline_ts: ISO | null }` →
+  sets / clears, echoes the resolved meta. 400 on malformed ISO.
+
+Every existing analytics endpoint accepts `?since=` (explicit
+override), `?since=all` (engine bypass), or omits `since` (meta
+default). The exported `parseSinceParam` helper has unit-test coverage
+pinning the tri-state contract. Responses include a `since` echo field
+so the dashboard renders the "Stats since" status pill without a
+separate roundtrip.
+
+### Added — Dashboard "Stats since" controls
+
+The Analytics tab's refresh bar gains a select + "Set baseline now" /
+"Clear baseline" buttons + an inline state pill. The dropdown's
+"Since baseline (default)" option mirrors the report's behaviour;
+"All time" bypasses; "Last 24 hours" / "Last 7 days" / "Custom" do what
+they say. Custom takes a free-form ISO string. Setting / clearing the
+baseline triggers a full analytics refresh so every widget reflects the
+change. The Markdown report header gains a "Stats since: …" field that
+echoes whichever filter the report was generated under, so an old
+export remains self-documenting.
+
+### Changed — Sample-size gate replaces inline label calcs
+
+Three Markdown-report rendering sites in `src/dashboard.js` (executive
+summary HARMFUL list, scorecard table, rule-performance table) and the
+live HTML rule-performance table now read `.label` from the server
+response and fall back to inline calculations only when the server
+didn't attach one. The previous behaviour of computing labels from raw
+effectiveness without a sample-size guard is gone.
+
+### Engine state — explicit bypass
+
+`src/server.js:syncDisabledRules` and `src/tools/server-status.js`
+auto-disable / disabled-rules snapshot now pass `since: null`
+explicitly. `resolveSince` recognises `null` as the engine bypass
+marker and returns it unchanged regardless of any operator baseline.
+This keeps the auto-disable loop and case-base scoring stable across
+baseline edits — operators can experiment with reporting windows
+without affecting the runtime engine state.
+
+### Tests
+
+- `tests/unit/analytics-store.test.js` — 7 new tests covering
+  baseline get / set / clear / persistence / rebuild-survival /
+  validation.
+- `tests/unit/analytics-labels.test.js` (new) — 27 tests pinning the
+  label contract, the sample-size gate at the threshold boundary, the
+  `unmatched` precedence, and the `withCheckLabels` / `withRuleLabels`
+  immutability.
+- `tests/unit/analytics-queries.test.js` — 14 new `since`-variant
+  tests, one per filterable function plus precedence cases.
+- `tests/unit/case-base.test.js` — 8 new tests covering the case-base
+  reporting paths plus a deliberate test that `scoreRule` has no
+  `since` parameter (engine-path invariant).
+- `tests/unit/http-since-param.test.js` (new) — 8 tests pinning the
+  HTTP-layer `?since=` parser tri-state contract.
+
+Total: 64 new tests. Full unit suite passes (1 pre-existing failure
+in `load-development-guide` expectation drift, unrelated to this
+change).
+
 ## 0.7.2 — 2026-04-28
 
 CAC predictor — opt-in 4th gating axis for the diagnostic emit
diff --git a/SYSTEM_ARCHITECTURE.md b/SYSTEM_ARCHITECTURE.md
new file mode 100644
index 0000000..fd0c2e2
--- /dev/null
+++ b/SYSTEM_ARCHITECTURE.md
@@ -0,0 +1,945 @@
+# pos-supervisor — system architecture
+
+A walkthrough of how the validator turns a `validate_code` call into a
+diagnostic with hints and proposed fixes, what every data file under
+`src/data/` actually does, what the dashboard's vocabulary
+(`unmatched`, `active`, `adoption`, `collateral`) actually measures, and
+how the adaptive engine and CAC predictor read analytics back into the
+emit path.
+
+The document is meant to make the system legible end-to-end: after
+reading it you should be able to look at a row in the dashboard and
+trace it backwards to a concrete file you can edit.
+
+---
+
+## 0. Reading guide for the report you generated
+
+The numbers from `pos-supervisor-report-2026-05-01_18-31-50.md` line up
+with the concepts below, so a quick orientation:
+
+- **Funnel: 357 emitted → 254 resolved (71%), 23 regressed (6%).**
+  254/357 windows were resolved across 71 sessions. That's "we said
+  something useful 7 times out of 10". 6% regression rate is low but
+  not zero — the agents took our fix and broke something else in 23
+  cases. Anything tagged `HARMFUL` in the rule table contributed to
+  those 23.
+- **Health score 15/100 (infrastructure only).** That's not "the
+  validator is broken" — it's "the dashboard's project-analysis tab was
+  never run on this DEMO project, so the project-shape dimensions stay
+  zero". Click "Analyze Project" once and the score takes its real
+  value.
+- **`PartialCallArguments`: 80 emits, 87% resolved, 10% regressed,
+  GOOD.** This is the workhorse — it fires the most and the agent
+  almost always gets it right. The fact that
+  `PartialCallArguments.unmatched` accounts for 49 of those 80 is the
+  interesting part: the rule engine doesn't have a specific
+  rule_id for ~60% of these emits, just the catch-all (see §4.4 below).
+  Adding a few `PartialCallArguments.` rules would be a real
+  effectiveness win.
+- **`MissingPage`: 14 emits, 25% resolved, LOW.** Most of those
+  14 are the self-page false positive we just fixed (Issue 4).
+  Resolution rate should climb on the next run.
+- **`NonGetRenderingPage.get_form_target`: 1 emit, 100% regressed,
+  -100% effectiveness, INSUFFICIENT_DATA.** Don't act on this row yet —
+  one regression on one emit is not enough signal. The
+  `INSUFFICIENT_DATA` label is doing exactly what it should: blocking
+  panic.
+- **`UNMATCHED` rule_ids dominating the bottom of the rule table.**
+  Every row labelled `UNMATCHED` is "the LSP fired this check, no rule
+  modulematched, so we tagged the diagnostic with `.unmatched`
+  and emitted it raw". Each one is a candidate for a new rule — the
+  bigger `Emitted` column the more impact a rule would have. The CLAUDE.md
+  prompt for adding a rule lives in §4 below.
+- **Knowledge gaps section says 100% coverage on every check.**
+  "Coverage" here means "does a rule module exist for this check name",
+  not "does a rule fire on every diagnostic". The two are different —
+  a check can have a rule module that only handles 1 of 10 sub-cases,
+  leaving 9 as `.unmatched`. Use the rule-performance table for the
+  finer-grained view.
+
+The rest of this document explains why each of those bullets is true.
+
+---
+
+## 1. The big picture in three boxes
+
+```
+┌──────────┐    ┌─────────────────────────────────┐    ┌────────┐
+│  Agent   │ →  │  validate_code (one tool call)  │ →  │ Agent  │
+└──────────┘    │                                 │    └────────┘
+                │  1. parse → AST                 │
+                │  2. lint  → raw diagnostics     │
+                │  3. enrich → hint, fix, conf.   │
+                │  4. pipeline → suppress/verify  │
+                │  5. CAC gate (optional)         │
+                │  6. shape response, log emit    │
+                └─────────────────────────────────┘
+                                │
+                                ▼
+                ┌────────────────────────────────┐
+                │  Analytics (closed loop)       │
+                │  validator_emit → SQLite       │
+                │  next call → window classifier │
+                │  → outcomes → case base        │
+                │  → engine state (next emit)    │
+                └────────────────────────────────┘
+```
+
+Three things are happening at once:
+
+1. **Synchronous** — the agent's `validate_code` call walks a fixed
+   pipeline and gets back errors, warnings, fixes, and a
+   `must_fix_before_write` boolean.
+2. **Persistent** — every emit is appended to
+   `.pos-supervisor/sessions//events.ndjson`, then ingested into
+   `analytics.db` (SQLite) for analysis.
+3. **Reflective** — the next time the same diagnostic fires, the
+   engine reads the analytics and adjusts: lower confidence, suppress,
+   downgrade severity, or auto-disable the rule.
+
+Boxes (2) and (3) are the "neuro" half of the
+neuro-symbolic split that the codebase calls the **adaptive engine**
+(see §6).
+
+---
+
+## 2. Vocabulary you must internalise first
+
+Mixing these up is the main reason the dashboard feels confusing.
+
+| Term            | What it actually is                                                                 | Lives in                                  |
+| --------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
+| **check**       | The name of an issue category emitted by the LSP / pos-cli check / our structural checks. Examples: `MissingPartial`, `LiquidHTMLSyntaxError`, `pos-supervisor:HtmlInPage`. The LSP picks it. | LSP / structural-warnings.js              |
+| **diagnostic**  | One concrete instance of a check at a (file, line, column) with a message.          | the LSP / our pipeline                    |
+| **rule**        | A piece of code (`src/core/rules/.js`) that turns a raw diagnostic into a richer one with a hint, suggested fix, and confidence number. Each check has 0..N rules; the engine picks one (first-match-wins, by priority). | rules/                                    |
+| **rule_id**     | The id the rule stamps onto the diagnostic — `MissingPartial.invalid_lib_prefix`. The dashboard groups by this. | set by `apply()` of the rule              |
+| **`.unmatched`** | A synthetic rule_id we stamp when no rule matched, so analytics bucket every emit. Tells you: "this check fired and our rule library had nothing to say". | populated in `populateDefaultConfidence()` in diagnostic-pipeline.js |
+| **hint**        | A markdown blob that explains the issue to the agent. Either inline (from the rule's `apply()`) or rendered from a template under `src/data/hints/.md`. | hints/ + rules                            |
+| **fix**         | A structured proposal — `text_edit`, `insert`, `create_file`, or `guidance`. Generated by `fix-generator.js` for a fixed set of checks; rules can also return their own. | fix-generator.js + rules                  |
+| **outcome**     | What happened between two consecutive `validate_code` calls on the same file: `resolved`, `regressed`, `unchanged`, `moved`. Computed by the **window classifier**. | window-classifier.js                       |
+| **fix_applied** | One of `verbatim`, `partial`, `ignored`, computed by comparing the file before/after the edit against any proposed fixes. | window-classifier.js → analytics-store.js |
+| **window**      | A pair of consecutive validate_code calls on the same (session, file). The unit of measurement. | window-classifier.js                       |
+| **window_id**   | Primary key of a `windows` row.                                                     | analytics-store.js                        |
+| **fp** / **template_fp** | Stable hashes — `fp = hash(check, file, message_template)`, `template_fp = hash(check, message_template)`. `fp` lets us track the same diagnostic across calls; `template_fp` groups variants of the same template. | diagnostic-record.js                      |
+| **collateral**  | When a fix is applied and the diagnostic resolves, but a NEW diagnostic appears at the same time — the agent broke something else. `collateral_added` = max(0, regressed - resolved) within the same window. | window-classifier.js                       |
+| **active rule** | A rule that is currently being run on incoming diagnostics. Same set as `_registry minus _disabledRules`. | engine.js                                 |
+| **adoption rate** | Of the windows where a fix was proposed for a diagnostic, how many ended with `fix_applied = 'verbatim'`. Per rule_id. | case-base.js                              |
+| **resolution rate** | Of the windows where a diagnostic with this rule_id was emitted, how many ended with `outcome = 'resolved'`. | case-base.js / analytics-queries.js       |
+| **regression rate** | Of the same population, how many ended with `outcome = 'regressed'` (the diagnostic came back at a different fp). | case-base.js / analytics-queries.js       |
+| **effectiveness** | `resolution_rate - regression_rate`. The headline number on the dashboard. | analytics-labels.js                       |
+
+Internalise that list and the rest reads itself.
+
+---
+
+## 3. The synchronous request lifecycle
+
+This is what happens during one `validate_code` call. The actual code
+lives in `src/tools/validate-code.js` and `src/core/diagnostic-pipeline.js`.
+
+### 3.1 Step 1 — parse
+
+```
+content (string)
+  └─→ parseLiquidFile(content)            # @platformos/liquid-html-parser
+        └─→ extractAllFromAST(ast)        # slug, layout, method, renders,
+                                          # graphql, filters, tags, doc_params, …
+```
+
+We parse with the platformOS Liquid parser in **tolerant** mode, walk
+the AST once with `liquid-parser.js:walk`, and produce a
+`structural` object that downstream steps read. This is the "ground
+truth" view of what the file actually does — slugs, methods, doc params,
+referenced partials, translations.
+
+If the parse fails entirely, we still continue: the linter step often
+catches the underlying syntax error and we want the agent to see *that*
+error, not a cascade of "could not parse" infos.
+
+### 3.2 Step 2 — lint (raw diagnostics)
+
+Two upstream sources, picked at runtime:
+
+- **LSP path** (default when `pos-cli lsp` is up). We forward
+  `textDocument/didOpen` with the in-memory content, await
+  `publishDiagnostics`, normalise into our internal diagnostic shape
+  (`{ check, severity, message, line, column, endLine, endColumn,
+   _filePath }`).
+- **check-runner fallback** (`pos-cli check run` subprocess). Used
+  when the LSP isn't running or crashed. Same diagnostic shape after
+  `parseCheckResult`.
+
+This step is the *only* place where check names enter the system. The
+universe of check names is defined upstream by `pos-cli`, plus our own
+`pos-supervisor:*` namespace from `structural-warnings.js`.
+
+### 3.3 Step 3 — enrich (rule engine + per-check fallbacks)
+
+Run inside `error-enricher.js:enrichAll`. For every diagnostic:
+
+1. **LSP hover** at the diagnostic position is attached as
+   `hover_docs`. Cached per (line, column) so duplicates are cheap.
+2. **Rule engine** (`runRules(diag, facts)`):
+   - The rule registry is keyed by check name. For
+     `MissingPartial`, it loads everything in
+     `src/core/rules/MissingPartial.js` (priority 5, 10, 20, 30, 40)
+     plus any **promoted rules** from
+     `.pos-supervisor/promoted-rules.json` (see §6.4) and any
+     `_disabledRules` are skipped.
+   - First rule whose `when(diag, facts)` returns truthy wins. Its
+     `apply(diag, facts)` returns `{ rule_id, hint_md, fixes,
+     confidence, see_also?, case_base_signal? }`.
+   - The result is folded into the diagnostic. If the check has rules
+     and a rule matched, we *skip* the per-check regex enrichment that
+     follows; the rule is authoritative.
+3. **Per-check regex enrichment fallback** (the older code path
+   that still handles ~half the checks). For checks like
+   `UnknownFilter`, `UndefinedObject`, `MetadataParamsCheck` etc., we
+   parse the raw LSP message with regexes, look up the symbol in our
+   indexes (`filtersIndex`, `objectsIndex`, `tagsIndex`,
+   `schemaIndex`), and produce a hint by rendering the appropriate
+   template under `src/data/hints/.md` with the extracted
+   variables. Shopify contamination detection happens here too —
+   `isShopifyObject` / `isShopifyFilter` against
+   `src/data/knowledge.json` (and the dedicated
+   `shopify-objects.json` / `shopify-contamination.json`).
+4. **Pinned see-also** — `attachSeeAlso` looks up the diagnostic in
+   `src/data/checks/.yml` for a curated "see also" link to
+   another tool (e.g. `domain_guide(commands, api)`).
+
+After this step every diagnostic has a `hint`, possibly a
+`suggestion`, a `rule_id` (or no rule_id yet — that gets stamped later
+in step 5), a `confidence` (or null), and possibly `fixes`.
+
+### 3.4 Step 4 — diagnostic post-processing pipeline
+
+`runDiagnosticPipeline()` in `src/core/diagnostic-pipeline.js`. This is
+where we suppress, downgrade, or annotate diagnostics that are
+known-false-positive for platformOS-specific reasons. Each step is a
+pure function over the result; the order is documented in the
+ORDERING CONTRACT comment at the top of the file.
+
+The current pipeline (post our most recent fix) is:
+
+```
+0.   userSuppressions                    # .pos-supervisor-ignore.yml
+0a.  suppressLspKnownFalsePositives      # NEW: assign x = a == b regression
+1.   suppressDocParams                   # @param X declared → no UndefinedObject(X)
+2.   suppressUnusedDocParams             # X used as named arg → not "unused"
+3.   elevateShopify                      # Shopify-* warnings → errors
+4.   deduplicateArgChecks                # MissingRender* covers MetadataParams*
+5.   suppressUndocumentedTargetParams    # MetadataParamsCheck on undocumented partial
+6.   suppressRequiredParamsWithDefault   # | default:'' in target → "required" is wrong
+7.   suppressModuleHelpers               # DeprecatedTag on module/* includes
+8.   suppressOrphanedPartial             # commands/queries are invoked dynamically
+9.   suppressByPending (files)           # MissingPartial for in-plan files
+10.  suppressByPending (pages)           # MissingPage for in-plan pages
+11.  suppressByPending (translations)    # TranslationKeyExists for in-plan keys
+12.  verifyMissingAssets                 # disk scan vs LSP cache
+13.  verifyTranslationKeysOnDisk         # disk scan vs LSP cache
+14.  verifyPageRoutesOnDisk              # NEW: also folds in in-memory overlay
+15.  verifyOrphanedPartialOnDisk         # disk scan finds callers
+16.  verifyMissingPartialsOnDisk         # disk scan vs LSP cache
+17.  populateDefaultConfidence           # stamp .unmatched + default conf
+```
+
+Each step emits at most one `pos-supervisor:*Suppressed` info
+diagnostic so the agent sees a single audit line per kind of
+suppression instead of being silently denied.
+
+The ORDERING CONTRACT exists because some steps depend on others
+having run already (e.g. the disk-verification steps run *after* the
+in-plan suppression so an in-plan file isn't double-counted).
+
+### 3.5 Step 5 — fix generation
+
+For full mode, `fix-generator.js:generateFixes` walks the surviving
+diagnostics and tries to attach a concrete `proposed_fixes` array.
+Four fix kinds:
+
+- **`text_edit`** — exact range replacement. Used for variable
+  renames, filter renames, slug normalisation, etc.
+- **`insert`** — insert text at a position. Used for `{% doc %}`
+  blocks, frontmatter additions.
+- **`create_file`** — create a missing file. Used for
+  `MissingPartial` / `MissingAsset` when the path is unambiguous.
+- **`guidance`** — description only, no machine-applicable edit. Used
+  when the right answer requires reasoning the linter can't do.
+
+A "scorecard" is also computed in full mode — a small array of
+`{ category, status, reason }` rows showing how the file scores against
+architectural concerns (e.g. doc-block coverage, layout
+correctness). It's displayed in the agent's response and also stored
+for later analysis.
+
+### 3.6 Step 6 — CAC predictor (optional gate)
+
+`cac-predictor.js:applyCac` runs over the surviving diagnostics if the
+operator has enabled it (state lives in
+`.pos-supervisor/cac-config.json`). For each surviving diagnostic it
+predicts the probability the agent will adopt the fix, then either
+allows, downgrades severity, or suppresses. Detail in §6.5.
+
+If CAC is in `shadow` mode, decisions are *recorded* but the result is
+not mutated — used to pre-flight a threshold change before flipping to
+`active`.
+
+### 3.7 Step 7 — shape the response, log the emit
+
+The final response includes:
+
+- `errors`, `warnings`, `infos` — the surviving diagnostics with all
+  the enrichment fields populated.
+- `proposed_fixes` — the fix-generator output.
+- `clusters` — diagnostics grouped by root-cause heuristic.
+- `scorecard` — the architectural scorecard.
+- `tips`, `domain_guide` — for full mode only.
+- `structural` — what we extracted from the AST.
+- `_pipelineTrace` — what each pipeline step removed (for the
+  dashboard's "Pipeline inspector" tab).
+- `status` — `'ok' | 'warning' | 'error'`.
+- `must_fix_before_write` — boolean. The single most important field
+  for the agent. If true, the agent is forbidden from writing the
+  file. Set whenever there's at least one error OR a "blocking
+  warning" survives (`OrphanedPartial`, `pos-supervisor:RemovedRender`,
+  etc. — the list is at the top of `validate-code.js`).
+- `next_step` — a deterministic prose paragraph telling the agent what
+  to do next.
+
+Finally we emit per-diagnostic `validator_emit` events to the session
+event log and a single `tool_call` event for the whole call. Both go to
+`.pos-supervisor/sessions//events.ndjson`.
+
+---
+
+## 4. The data files and their roles
+
+`src/data/` is a small read-mostly knowledge base that backs both the
+synchronous validation path and the `lookup` / `domain_guide` /
+`module_info` tools. Each file has a tightly defined role; mixing them
+up is the main reason hints sometimes feel out of place.
+
+### 4.1 `src/core/rules/.js` — the rules
+
+What the registry calls a "rule". One JS file per check, each
+exporting `rules: Rule[]` that gets loaded via
+`src/core/rules/index.js:loadAllRules`.
+
+**A rule object:**
+
+```js
+{
+  id:       'MissingPartial.invalid_lib_prefix',
+  check:    'MissingPartial',
+  priority: 5,                              // lower = matched first
+  when:     (diag, facts) => boolean,       // gate predicate
+  apply:    (diag, facts) => ({
+    rule_id:    'MissingPartial.invalid_lib_prefix',
+    hint_md:    '...markdown...',
+    fixes:      [{ type: 'text_edit', ... }],
+    confidence: 0.95,                        // 0..1
+    see_also:   { tool, args, reason },     // optional
+  }),
+}
+```
+
+The priority order is the load-bearing detail. The first rule whose
+`when` returns truthy wins. So `MissingPartial.invalid_lib_prefix`
+(priority 5) runs *before* `MissingPartial.module_path` (priority 10)
+and `MissingPartial.suggest_nearest` (priority 30) — by the time
+"suggest a nearest match" runs we know the path doesn't have the
+known-bad `lib/` prefix.
+
+### 4.2 `src/data/hints/.md` — hint templates
+
+A markdown file rendered by `hint-loader.js:getHint`. Supports
+`{{var}}` substitution. Used by the **per-check regex enrichment
+fallback** path — i.e. the older code path that runs when no rule is
+registered, or as a default when a rule doesn't include `hint_md`.
+
+Two categories of hints exist:
+
+- **Generic** — `MissingPartial.md`. Used as the default for the check.
+- **Specialised** — `MissingPartial-invalid_lib_prefix.md`,
+  `MissingPartial-module.md`. Picked by the regex enrichment path
+  based on params extracted from the message.
+
+A hint can also live inline in a rule's `apply()` (the `hint_md`
+field). When both exist, the rule's `hint_md` wins. As we migrate more
+checks into the rule engine, the hints/ folder becomes the fallback,
+not the primary surface.
+
+### 4.3 `src/data/checks/.yml` — check metadata
+
+A small YAML descriptor per check:
+
+```yaml
+name: MissingPartial
+summary: Referenced partial/command/query file does not exist
+hint:
+  default: 'Create the missing file. Partials: …'
+```
+
+Used by:
+
+- `domain_guide` and `lookup` tools — they show the `summary` and
+  `hint.default` to give agents quick orientation.
+- The rule-engine fallback when a rule doesn't supply `hint_md`.
+- The dashboard's check inventory tab.
+
+This is the "TL;DR" surface for each check. The hints/ template is
+where the long-form fix steps live.
+
+### 4.4 `src/data/knowledge.json` — pinned domain facts
+
+Most general-purpose data the validator needs. Top keys:
+
+- `version`
+- `checks` — pinned per-check "summary" + "hint" objects + Shopify
+  contamination lists. This is consumed by `knowledge-loader.js`.
+- `language_features` — same content as `language-features.yml`,
+  inlined for fast lookup. (See §4.7.)
+- `domains` — per-domain rules and triggered gotchas (see `domain-gotchas.yml`).
+- `content_triggers` — pattern → guidance (see `content-triggers.yml`).
+- `modules_missing_docs` — list of module helpers known to ship without
+  `{% doc %}` blocks; the suppressUndocumentedTargetParams pipeline
+  step trusts this list.
+
+Edits here propagate everywhere: a new entry in `checks.UnknownFilter.shopify_filters` immediately changes how `error-enricher.js` classifies an `UnknownFilter` for `money_with_currency`.
+
+### 4.5 `src/data/content-triggers.yml` — pattern advisories
+
+A list of `{ id, pattern, message, severity, domains }` rules. Patterns
+are regexes; when the file's *content* matches, the validator emits a
+"tip" (advisory info diagnostic) in the response. Used for things that
+don't fit the LSP's check vocabulary:
+
+```yaml
+- id: raw_filter_xss
+  pattern: \|\s*raw\s*[%}]
+  message: 'XSS risk: | raw disables HTML escaping…'
+  severity: security
+  domains: [pages, partials, layouts]
+```
+
+The triggering happens in `getContentTriggers()` (called from
+`validate-code.js`). These are *not* errors and do *not* contribute to
+`must_fix_before_write` — they're shown under `tips:` in the response.
+
+### 4.6 `src/data/domain-gotchas.yml` — domain-aware reminders
+
+Domain-specific advisories keyed by the file's domain (which we infer
+from path via `domain-detector.js`):
+
+```yaml
+pages:
+  rule: 'Pages are controllers — logic only, no inline HTML…'
+  gotchas:
+    - id: pages_context_prefix
+      trigger: has_check:UndefinedObject
+      message: 'Use context.params, context.session, …'
+      severity: required
+```
+
+`trigger` decides when the gotcha fires. Three forms:
+
+- `always` — every validation in this domain.
+- `has_check:` — only when the diagnostic list contains that
+  check.
+- `uses_tag:` — only when the file uses that tag (e.g. `try`).
+
+`getTriggeredGotchas` returns the matching ones; they end up in
+`domain_guide` (in full mode) and in the `domain_guide` tool's output.
+
+### 4.7 `src/data/language-features.yml` — Liquid feature reference
+
+Authoritative reference for platformOS-specific Liquid extensions:
+`try_catch`, `theme_render_rc`, `liquid_doc`, hash literals, array
+literals, etc. Used by `lookup` and the agent-facing domain guide. The
+contents are also mirrored under `knowledge.json:language_features` so
+runtime lookups are JSON-backed.
+
+If you add a new Liquid feature, write the entry here, regenerate
+`knowledge.json` from this file, and the rest of the system picks it
+up.
+
+### 4.8 `src/data/modules-missing-docs.json` — known undocumented helpers
+
+A flat list of paths under `modules/*` that the validator should treat
+as "undocumented partial" without disk verification:
+
+```json
+{
+  "modules": [
+    "modules/core/commands/execute",
+    "modules/admin-ui/views/partials/header",
+    ...
+  ]
+}
+```
+
+The pipeline step `suppressUndocumentedTargetParams` reads this and
+suppresses `MetadataParamsCheck` for any function/render call into
+those paths (since the LSP would otherwise flag every required-param
+case based on inferred-from-usage params, all of them false
+positives).
+
+This file is the safety hatch for "the upstream module doesn't ship a
+`{% doc %}` and we can't change the upstream module".
+
+### 4.9 `src/data/domains/.md` and `references/`
+
+Long-form documentation served by the `domain_guide` and `lookup` tools.
+Not consumed by the validator's emit path — these are agent reading
+material. `domains/commands.md`, `domains/pages.md`, etc. are the
+canonical source for "how do you write a command, the platformOS way".
+
+### 4.10 `src/data/shopify-objects.json`, `shopify-contamination.json`
+
+Pinned lists of Shopify-only identifiers (objects, filters, tags) that
+should never appear in platformOS code. Consumed by `knowledge-loader.js`
+and `error-enricher.js` to elevate `UndefinedObject('product')` from
+"variable not found" to "Shopify contamination — platformOS doesn't
+have this object". The "elevateShopify" pipeline step turns those
+warnings into errors.
+
+### 4.11 `src/data/resources/`
+
+Read once at server startup and exposed as MCP resources. Currently:
+`platformos-synthesis.md`, the agent's session-startup primer.
+
+### Summary table
+
+| File / dir                              | Read by                              | Write surface for what                   |
+| --------------------------------------- | ------------------------------------ | ---------------------------------------- |
+| `src/core/rules/.js`             | `rules/engine.js`                    | A rule that turns one check into a rich diagnostic + fix. |
+| `src/data/hints/.md`             | `hint-loader.js` → enricher fallback | Long-form fix steps for the agent.       |
+| `src/data/checks/.yml`           | `domain_guide`, `lookup`, dashboard  | Short summary + default hint per check.  |
+| `src/data/knowledge.json`               | `knowledge-loader.js`                | All the pinned check + domain + Shopify metadata in one place. |
+| `src/data/content-triggers.yml`         | `getContentTriggers()`               | "When the file contains this pattern, also tell the agent X" advisories. |
+| `src/data/domain-gotchas.yml`           | `getTriggeredGotchas()`              | Per-domain reminders, optionally gated by check or tag. |
+| `src/data/language-features.yml`        | `lookup`, `domain_guide`             | Reference docs for platformOS Liquid extensions. |
+| `src/data/modules-missing-docs.json`    | suppressUndocumentedTargetParams     | "Trust me, this module helper has no doc — don't flag callers". |
+| `src/data/domains/.md`          | `domain_guide`                       | Long-form domain documentation.          |
+| `src/data/references//`          | `lookup`                             | Curated reference docs.                  |
+| `src/data/shopify-objects.json` etc.    | `knowledge-loader.js`                | Shopify contamination detection lists.   |
+
+---
+
+## 5. What the dashboard words mean
+
+The dashboard (`/dashboard.html`, served from `src/dashboard.js` over
+HTTP from `src/http-server.js`) summarises the analytics SQLite
+database, so its terms are the analytics vocabulary plus a few labels.
+
+### 5.1 Outcomes (per diagnostic, per window)
+
+`window-classifier.js` takes two consecutive `validate_code` calls on
+the same file and labels each diagnostic from the *first* call with
+one of four outcomes:
+
+| Outcome      | Meaning                                                                |
+| ------------ | ---------------------------------------------------------------------- |
+| `resolved`   | The diagnostic's `fp` was present in the start call, absent in the end call. The agent fixed it. |
+| `regressed`  | A `fp` *not* in the start call appears in the end call. New diagnostic introduced. |
+| `unchanged`  | Same `fp` present in both start and end. The agent didn't fix it.      |
+| `moved`      | The `template_fp` is present in both, but the `fp` changed. Same root cause, different line — usually because the agent edited surrounding code and the diagnostic shifted. |
+
+A fifth, `write_unverified`, exists for windows where we never saw a
+follow-up call (the agent gave up or moved on).
+
+### 5.2 fix_applied (per outcome)
+
+For non-regressed outcomes, we compare the file's content range against
+any `proposed_fixes` we emitted:
+
+| Value      | Meaning                                                                  |
+| ---------- | ------------------------------------------------------------------------ |
+| `verbatim` | The agent applied the proposed fix exactly. This is the strongest "they listened to us" signal. |
+| `partial`  | The fix range was modified, but not exactly as proposed.                |
+| `ignored`  | The content in the fix range is unchanged (yet the diagnostic resolved or regressed for some other reason). |
+| `null`     | We didn't propose a fix for that diagnostic.                            |
+
+### 5.3 collateral
+
+Inside a single window: how many *new* diagnostics did the fix
+introduce? `max(0, regressed - resolved)`. Used to penalise rules whose
+"fix" creates more bugs than it solves.
+
+A rule with high effectiveness (`resolution - regression`) but high
+collateral is doing more harm than it looks: each emit it resolves
+also births a fresh diagnostic, just somewhere else.
+
+### 5.4 adoption rate
+
+For a rule_id over many windows: `adopted / total_outcomes` where
+`adopted = COUNT(outcomes WHERE fix_applied = 'verbatim')`. "When this
+rule fired and we proposed a fix, how often did the agent take it
+verbatim".
+
+A low adoption rate doesn't directly mean the rule is wrong — sometimes
+agents prefer their own phrasing — but it strongly correlates with
+"the fix doesn't actually do what it claims".
+
+### 5.5 resolution / regression / effectiveness
+
+| Metric           | Definition                                                              |
+| ---------------- | ----------------------------------------------------------------------- |
+| Resolution rate  | `resolved / total_outcomes` per rule_id. "How often the diagnostic ends up fixed in the next call". |
+| Regression rate  | `regressed / total_outcomes` per rule_id. "How often the same rule reappears as a NEW diagnostic in the next call". (Note: a regression is on the rule_id, not necessarily the same `fp`.) |
+| Effectiveness    | `resolution_rate - regression_rate`. Goes from `-1` (every emit causes a regression) to `+1` (every emit ends in resolution). The headline rule-quality number. |
+
+### 5.6 Labels
+
+`src/core/analytics-labels.js` gates labels by sample size
+(`LABEL_MIN_OUTCOMES = 5`) so a rule that fired once with a single
+regression doesn't headline as `HARMFUL -100%`.
+
+**Per-check labels (scorecard):**
+
+| Label              | Meaning                                                              |
+| ------------------ | -------------------------------------------------------------------- |
+| `INSUFFICIENT_DATA`| `total_outcomes < 5`. We don't know yet.                              |
+| `GOOD`             | `effectiveness > 0.5`.                                                |
+| `OK`               | `0.15 < effectiveness ≤ 0.5`.                                         |
+| `LOW`              | `0 ≤ effectiveness ≤ 0.15`.                                           |
+| `HARMFUL`          | `effectiveness < 0`. The hint or fix is making things worse.         |
+
+**Per-rule labels (rule-performance table):**
+
+| Label              | Meaning                                                              |
+| ------------------ | -------------------------------------------------------------------- |
+| `UNMATCHED`        | The rule_id is `.unmatched` — i.e. we emitted the diagnostic with no matching rule. **Always wins** even at low samples; coverage gap is actionable. |
+| `INSUFFICIENT_DATA`| Real rule, but `< 5` outcomes. Wait.                                  |
+| `AT RISK`          | Real rule, ≥ 5 outcomes, `effectiveness < 0.15`. Look at it.          |
+| `OK`               | Real rule, ≥ 5 outcomes, `effectiveness ≥ 0.15`. Healthy.             |
+
+### 5.7 Active / disabled / probation / promoted / force-disabled
+
+The state of a rule_id in the **rule registry** at a moment in time.
+Defined in `engine.js`:
+
+| State               | Set membership                                            |
+| ------------------- | --------------------------------------------------------- |
+| **active**          | In `_registry` and *not* in `_disabledRules`. Will run on the next emit. |
+| **disabled**        | In `_disabledRules` — the case-base auto-disabled it because effectiveness is bad. Skipped on emit. |
+| **force-enabled**   | In `_forceEnabled` (operator override). Runs even if `_disabledRules` lists it. |
+| **force-disabled**  | In `_forceDisabled` (operator kill-switch). Never runs, no matter what analytics say. |
+| **probation**       | A *promoted* rule's first 100 emits. If it crosses some quality bar in those 100, probation is resolved and it becomes a regular rule. Otherwise it gets demoted. |
+| **promoted**        | Came from `.pos-supervisor/promoted-rules.json` rather than `src/core/rules/.js`. Hand-authored or operator-promoted from a case-base suggestion. |
+
+Note the dashboard mixes "active rule" (the engine concept above) with
+"active CSS class" (the UI concept of the currently-selected tab). On
+the dashboard, "active" near a rule_id means the engine concept; near
+a tab means the UI concept.
+
+### 5.8 since / baseline
+
+The dashboard's "Stats since" dropdown chooses a window:
+
+- **Since baseline** — the operator's chosen "fresh start" timestamp,
+  stored in `meta.analytics_baseline_ts`.
+- **All time** — engine-state callers always read all time, regardless
+  of the operator's baseline.
+- **Last 24h / 7d / Custom** — the obvious thing.
+
+Engine state (case-base auto-disable, probation resolution, CAC
+predictor) deliberately does NOT respect the operator's baseline — a
+narrow window can produce statistically meaningless decisions.
+Reporting respects it. See the `resolveSince` contract in
+`case-base.js`.
+
+---
+
+## 6. The adaptive engine
+
+The adaptive engine is the closed loop: emits land in the analytics
+database, the case base reads them back, and the engine adjusts its
+behaviour for the next emit.
+
+### 6.1 Engine modes
+
+`src/core/engine-mode.js` defines two states stored in
+`.pos-supervisor/engine-mode.json`:
+
+- **static** — every rule fires at its raw confidence, no case-base
+  scoring, no auto-disable, no promoted rules. Behaves like a classic
+  static linter.
+- **adaptive** — case-base scoring ON, auto-disable ON, promoted
+  rules loaded ON.
+
+Analytics collection happens in *both* modes — only consumption
+changes. You can run static for a week, accumulate data, switch to
+adaptive when the case base is dense enough to be useful.
+
+### 6.2 Per-emit scoring
+
+When a rule's `apply()` returns a result, `engine.js:applyCaseBaseScoring`
+runs (only in adaptive mode):
+
+```
+scoreRule(store, rule_id, template_fp)
+  → null       if < MIN_CASES (3) emits for this (rule, template)
+  → null       if no outcomes recorded
+  → { adjustment: number, reason: string }
+```
+
+The adjustment is bounded in `[-0.3, +0.3]` and shifts the rule's
+emitted `confidence`. A rule with a 90% resolution rate on a specific
+template gets a +0.2 boost; a rule with a 30% resolution rate gets a
+−0.2 penalty. The `case_base_signal` field on the outgoing diagnostic
+records the adjustment so the dashboard can show it.
+
+### 6.3 Auto-disable
+
+`case-base.js:ruleScores` runs periodically (`server.js:syncDisabledRules`).
+Any rule with `effectiveness < 0.15` *and* `total_outcomes ≥ 10` is
+added to `_disabledRules`. The threshold is intentionally
+conservative: 10 outcomes is enough that the Beta posterior has
+collapsed from "wide" to "informative", but not so high that bad rules
+linger.
+
+Auto-disable is *override-able* by the operator: the dashboard can
+mark a rule `force_enable` (it runs even though analytics disabled it)
+or `force_disable` (it never runs, even if a rule module re-registers
+it). Both override sets are persisted in
+`.pos-supervisor/rule-overrides.json`.
+
+### 6.4 Promoted rules
+
+`src/core/rules/promoted-rules.js` loads
+`.pos-supervisor/promoted-rules.json` — declarative rules entered
+through the dashboard's "Suggestion → Promote" flow. The flow is:
+
+1. Case base finds a `template_fp` with consistent agent behaviour but
+   no matching rule (`synthesizeGuardPredicate`).
+2. The dashboard suggests "consider adding a rule for this pattern".
+3. The operator reviews and clicks Promote, optionally tweaking the
+   guard / hint.
+4. The promoted rule lands in `promoted-rules.json` and becomes part
+   of the registry on the next reload — running in **probation** for
+   its first ~100 emits, then either auto-resolving (effectiveness
+   ≥ 0.5 sustained) or auto-demoting.
+
+The point of the probation stage is that a hand-authored rule is a
+guess based on a case-base pattern that *might* generalise. We measure
+it before trusting it.
+
+### 6.5 CAC predictor
+
+CAC = "case-based action classifier". It's a *fourth* gating axis on
+top of severity / static confidence / adaptive-mode scoring.
+
+For each surviving diagnostic post-pipeline, `applyCac`:
+
+1. Computes an **empirical-Bayes adoption probability** using the
+   hierarchical scorer in `scoreFixHelpfulness`:
+   - try `(rule_id, file_domain)` — most specific
+   - fall back to `rule_id`
+   - fall back to `severity`
+   - fall back to the prior (Beta(2,2) → 0.5)
+2. Decides: `allow`, `downgrade` (severity by one step), or
+   `suppress` — based on `config.threshold` and `config.action`.
+3. Mutates the result in `active` mode; in `shadow` mode just records
+   the decision.
+
+The classifier is *always* safe — it can only suppress or downgrade,
+never produce a new diagnostic, never alter a fix proposal. If the
+predictor crashes, the result passes through unchanged.
+
+CAC is opt-in. Default is disabled. Operators turn it on after enough
+analytics accumulate to make the Bayes scorer informative.
+
+### 6.6 The full feedback loop, illustrated
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│   t = 0   agent calls validate_code                            │
+│           rule R fires, confidence c=0.7, fix F proposed       │
+│           validator_emit logged                                 │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+┌──────────────── t = 1 (ms)    ▼ ─────────────────────────────────┐
+│   agent applies fix F, calls validate_code on the file again    │
+│   pos-supervisor runs window classifier:                         │
+│     start_diags ∋ {fp_X}  end_diags ∌ {fp_X}                    │
+│     → outcome[fp_X] = 'resolved', fix_applied = 'verbatim'      │
+│   one row in `outcomes` table                                    │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+┌──────────────── t = 2 (next call by anyone) ▼ ─────────────────┐
+│   rule R fires again on a different file, same template_fp     │
+│   case base looks up scoreRule(R, template_fp):                │
+│     stats: 3 emits, 3 resolved, 0 regressed → adjustment +0.2   │
+│   diagnostic confidence boosted to 0.9                         │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+┌──────────────── t = N (hours later, > 10 emits) ▼ ─────────────┐
+│   server.js:syncDisabledRules runs case-base.ruleScores        │
+│   rule R: effectiveness 0.85, n=12 → not disabled              │
+│   rule R': effectiveness -0.4, n=15 → added to _disabledRules │
+│     → R' won't fire on the next emit until operator overrides │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Three timescales: per-emit scoring (`scoreRule`), per-batch
+auto-disable (`ruleScores`), and ad-hoc promotion / probation. They
+are all reading the same `outcomes` table, just at different
+aggregation levels.
+
+---
+
+## 7. How an error becomes a hint, fix, and explanation — worked example
+
+Take the case the agent hit in DEMO: `MissingPartial` for
+`'lib/queries/contact_submissions/create'`. Trace it:
+
+1. **LSP** fires `MissingPartial` with message
+   `"'lib/queries/contact_submissions/create' does not exist"`.
+2. **`normalizeLspDiagnostics`** turns the LSP shape into our internal
+   diagnostic `{ check: 'MissingPartial', message: '…', line, column,
+   _filePath }`.
+3. **`enrichAll`** runs:
+   - `extractParams('MissingPartial', message)` extracts
+     `{ partial: 'lib/queries/contact_submissions/create' }`.
+   - `templateOf` produces a fingerprintable template:
+     `"'' does not exist"`.
+   - `runRules(diag, facts)` walks rules in priority order:
+     - `MissingPartial.invalid_lib_prefix` (priority 5) —
+       `when(diag)` checks if the partial path starts with `lib/commands/`
+       or `lib/queries/`. It does. Wins.
+     - `apply(diag)` builds the hint: "Drop the invalid `lib/`
+       prefix… Use `queries/contact_submissions/create` instead." A
+       text_edit fix is generated that removes the `lib/` prefix from
+       the source.
+   - The diagnostic's `rule_id` becomes
+     `MissingPartial.invalid_lib_prefix`, `confidence` is set to
+     `0.95`, `fixes` includes the text_edit, `hint` is the markdown.
+4. **Pipeline** runs:
+   - `userSuppressions`: not configured. Pass.
+   - `suppressLspKnownFalsePositives`: only matches
+     `LiquidHTMLSyntaxError`. Pass.
+   - …
+   - `suppressByPending(MissingPartial)`: looks up the partial name
+     against `buildPendingPartialNames(pendingFiles)`. The pending list
+     contains `app/lib/queries/contact_submissions/create.liquid`,
+     which expands to short-name `queries/contact_submissions/create`.
+     The diagnostic's name is `lib/queries/...` — does NOT match. Pass
+     (correctly).
+   - `verifyMissingPartialsOnDisk`: tries
+     `app/lib/lib/queries/contact_submissions/create.liquid` — does
+     not exist. Confirms the LSP. Pass.
+   - `populateDefaultConfidence`: rule already set rule_id and
+     confidence, so this is a no-op.
+5. **Fix generator** sees the rule already provided `fixes`, so it
+   doesn't add anything else.
+6. **CAC** (if enabled) looks up
+   `(MissingPartial.invalid_lib_prefix, file_domain=pages)` history.
+   Suppose 4 prior emits, 4 verbatim adoptions → high probability,
+   `allow`.
+7. **Response shape**:
+   - `errors[0]` = the enriched diagnostic, with hint, suggestion,
+     rule_id, confidence, fixes, hover_docs.
+   - `must_fix_before_write` = true.
+   - `next_step` tells the agent to apply the fix and re-validate.
+8. **Emit log**: a `validator_emit` event is written with `fp`,
+   `template_fp`, `rule_id`, `proposed_fixes` info; a `tool_call`
+   event wraps the whole call.
+9. **Next call** on the same file — agent has dropped the `lib/`
+   prefix. Window classifier sees `fp_X` absent in the end set →
+   `outcome = 'resolved'`, `fix_applied = 'verbatim'` (assuming the
+   text edit was applied as proposed). Both go into `outcomes`.
+10. **Aggregation**: case-base sees this rule's effectiveness inch
+    up. Future emits of the same template_fp get a small confidence
+    boost via `scoreRule`.
+
+That same trace applies, with different rules selected at step 3, to
+every diagnostic the system emits. The skeleton is uniform; only the
+rule logic and the data files behind the hints change per check.
+
+---
+
+## 8. Where the gaps are right now
+
+Reading from the report and the codebase together:
+
+1. **Rule coverage on `PartialCallArguments`.** 49 of 80 emits are
+   `.unmatched`. The rule module exists (5 priorities) but it covers
+   `required_render` / `required_function` / `unknown_render` /
+   `unknown_function` / a default — not the full surface of upstream
+   messages. Adding a few targeted variants would shave that
+   `.unmatched` count substantially.
+2. **`MissingPage` resolution rate.** The bulk of the 25% number is
+   the self-page false positive we just fixed. The next run should
+   show this climbing toward `MissingPartial`'s level.
+3. **`OrphanedPartial` resolution rate.** 50%. The pipeline already
+   suppresses orphan flags on commands/queries; the surviving 50% are
+   real partials that the agent doesn't always know how to wire. A
+   concrete `OrphanedPartial.` rule with a "where could this
+   be rendered from?" suggestion would help.
+4. **`pos-supervisor:NonGetRenderingPage`** — the `get_form_target`
+   variant has 1 emit / 100% regression in the report. It's a known
+   pattern (form action pointing at a GET-only page) and the rule
+   should produce a much more specific fix proposal.
+5. **`UnusedAssign.generic`** — 12 emits, 83% resolved, but the
+   suggestion is currently generic. A "if this is intentional, prefix
+   with `_`" hint would close the rest.
+6. **CAC adoption is at the prior** (`feature: prior, p_adopted: 0.5`)
+   for most rules in the DEMO data. We need ~50+ outcomes per
+   `(rule_id, domain)` before CAC has signal — keep collecting before
+   flipping to `active`.
+7. **Probation tracking is implemented but the dashboard's
+   "Suggestion → Promote" flow is sparse** — case-base
+   `synthesizeGuardPredicate` exists but the UI for reviewing
+   suggestions could be tighter; that's where most of the new-rule
+   throughput should come from once data accumulates.
+
+The actionable work is at the rule layer, not the pipeline layer:
+every `.unmatched` row in the rule-performance table is a missing rule
+in `src/core/rules/.js`. Pick the rows with the highest
+`Emitted` count and write rules for them.
+
+---
+
+## 9. Putting it all together
+
+To restate the system in one paragraph:
+
+The validator's *symbolic* core is `validate_code` walking a fixed
+pipeline (parse → lint → enrich → suppress/verify → fix → respond),
+backed by `src/core/rules/` for per-check logic and `src/data/` for the
+domain knowledge those rules read. Its *neural* side is the analytics
+loop: every emit is logged, the window classifier turns consecutive
+calls into outcomes, the case base aggregates outcomes into per-rule
+effectiveness, and the engine reads that back to score, disable, or
+override rules on the next call. The dashboard is a window into the
+analytics — labels like `GOOD`, `AT RISK`, `UNMATCHED` summarise the
+case base's view of whether a rule is helping or hurting. CAC is a
+fourth axis that uses the same analytics to predict whether the agent
+will adopt the proposed fix at all, allowing the validator to suppress
+diagnostics whose fix rarely lands.
+
+The improvement levers, in order of ROI:
+
+1. **Write rules for `.unmatched` rows** with high emit counts.
+2. **Tighten hints for `LOW` and `HARMFUL` checks** — those are
+   actively misleading agents.
+3. **Watch `regression_rate` over time** — a rule with a rising
+   regression rate has a hidden bug in its fix proposal.
+4. **Promote case-base suggestions** through the dashboard once
+   `synthesizeGuardPredicate` surfaces them — this is the rule-
+   authoring channel that scales without manual code review.
+5. **Flip CAC to `active` only after** `(rule_id, domain)` history has
+   ≥ 50 outcomes per cohort. Until then, CAC's prediction is the
+   prior and adds nothing.
+
+If you only remember three things from this document:
+
+- **The pipeline is symbolic and ordered**; every step is a documented
+  function and the order is load-bearing.
+- **`.unmatched` is the actionable signal**; every row tells you
+  exactly which `src/core/rules/.js` needs a new rule.
+- **Effectiveness is the only number that matters**, and it's gated by
+  `LABEL_MIN_OUTCOMES = 5`. Anything `INSUFFICIENT_DATA` is just
+  noise — wait for more data.
diff --git a/package.json b/package.json
index 1662187..023a210 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@platformos/pos-supervisor",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "platformOS domain-specific MCP server for LLM agents",
   "type": "module",
   "bin": {
diff --git a/src/core/analytics-labels.js b/src/core/analytics-labels.js
new file mode 100644
index 0000000..75311b5
--- /dev/null
+++ b/src/core/analytics-labels.js
@@ -0,0 +1,126 @@
+/**
+ * Analytics labels — single source of truth for the GOOD / OK / LOW / HARMFUL,
+ * AT RISK / UNMATCHED, and INSUFFICIENT_DATA presentation-layer labels.
+ *
+ * Pure functions, intentionally side-effect-free. The HTTP layer attaches
+ * `.label` to each scorecard / rule-performance row before serialising; the
+ * dashboard browser code and Markdown report consume that field directly so
+ * label logic isn't duplicated (or drifted) between server and client.
+ *
+ * INSUFFICIENT_DATA gate (`LABEL_MIN_OUTCOMES`) is the load-bearing change.
+ * Labels computed from a sample of one — `AT RISK -100%` on a single
+ * regression — are statistically meaningless and previously caused operators
+ * to chase ghosts of already-fixed rules. Below the threshold we return a
+ * neutral label that says "we don't know yet" instead of a confident wrong
+ * answer.
+ *
+ * The threshold is conservative on purpose: 5 outcomes lets a Beta(2,2)
+ * posterior collapse from "wide ribbon" to a meaningful interval. Engine-side
+ * decisions (auto-disable in case-base.ruleScores) use a stricter gate of 10
+ * because promotion/demotion is more consequential than display.
+ */
+
+export const LABEL_MIN_OUTCOMES = 5;
+
+/**
+ * Normalise a Beta-posterior object or bare number to a scalar in [0, 1].
+ * Mirrors the dashboard `rateVal()` helper exactly so the server emits the
+ * same labels the browser would have computed inline.
+ */
+function asRate(r) {
+  if (r && typeof r === 'object' && typeof r.mean === 'number') return r.mean;
+  if (typeof r === 'number') return r;
+  return 0;
+}
+
+/**
+ * Per-check scorecard label.
+ *
+ * Accepts a row from `checkScorecards()` carrying `.resolution_rate`,
+ * `.mislead_rate`, and either `.sample_size` (preferred) or `.total_outcomes`.
+ * Each rate may be a Beta posterior `{ mean, lower95, upper95 }` or a number.
+ *
+ * Returns one of:
+ *   - INSUFFICIENT_DATA — fewer than LABEL_MIN_OUTCOMES outcomes
+ *   - GOOD             — effectiveness > 0.5
+ *   - OK               — 0.15 < effectiveness <= 0.5
+ *   - LOW              — 0    <= effectiveness <= 0.15
+ *   - HARMFUL          — effectiveness < 0
+ */
+export function checkLabel(card) {
+  if (!card || typeof card !== 'object') return 'INSUFFICIENT_DATA';
+  const sampleSize = Number(card.sample_size ?? card.total_outcomes ?? 0);
+  if (!Number.isFinite(sampleSize) || sampleSize < LABEL_MIN_OUTCOMES) {
+    return 'INSUFFICIENT_DATA';
+  }
+  const effectiveness = asRate(card.resolution_rate) - asRate(card.mislead_rate);
+  if (effectiveness > 0.5)   return 'GOOD';
+  if (effectiveness > 0.15)  return 'OK';
+  if (effectiveness >= 0)    return 'LOW';
+  return 'HARMFUL';
+}
+
+/**
+ * Per-rule_id performance label.
+ *
+ * Accepts a row from `rulePerformance()` / `ruleScores()` carrying
+ * `.unmatched`, `.effectiveness`, and `.total_outcomes`.
+ *
+ * Precedence:
+ *   1. UNMATCHED       — `.unmatched === true` always wins. Coverage gap is
+ *                        actionable regardless of sample size; one emit on a
+ *                        rule-less check still tells the operator a rule needs
+ *                        writing.
+ *   2. INSUFFICIENT_DATA — `total_outcomes < LABEL_MIN_OUTCOMES`. We don't
+ *                          know enough to call the rule risky.
+ *   3. AT RISK         — effectiveness < 0.15. Real signal, real concern.
+ *   4. OK              — everything else.
+ *
+ * Note: `effectiveness` here is `resolution_rate - regression_rate`, not the
+ * 0..1 percentage the case-base disable-gate uses. A negative number is
+ * possible (rule causes more regressions than it resolves).
+ */
+export function ruleLabel(rule) {
+  if (!rule || typeof rule !== 'object') return 'INSUFFICIENT_DATA';
+  if (rule.unmatched) return 'UNMATCHED';
+  const totalOutcomes = Number(rule.total_outcomes ?? 0);
+  if (!Number.isFinite(totalOutcomes) || totalOutcomes < LABEL_MIN_OUTCOMES) {
+    return 'INSUFFICIENT_DATA';
+  }
+  const effectiveness = Number(rule.effectiveness ?? 0);
+  if (!Number.isFinite(effectiveness)) return 'INSUFFICIENT_DATA';
+  if (effectiveness < 0.15) return 'AT RISK';
+  return 'OK';
+}
+
+/**
+ * Filter scorecards down to the rows that warrant a HARMFUL headline in the
+ * Markdown report's executive summary. Honours the same sample-size gate so
+ * we don't trumpet "HARMFUL" off a single regression — which is exactly the
+ * stale-data trap that motivated this whole module.
+ */
+export function harmfulSummary(scorecards) {
+  if (!Array.isArray(scorecards)) return [];
+  return scorecards.filter(c => checkLabel(c) === 'HARMFUL');
+}
+
+/**
+ * Attach a `.label` field to every row in a scorecard array. Returns a NEW
+ * array; rows are shallow-copied so callers can't accidentally mutate the
+ * underlying analytics-queries result. HTTP handlers wrap the array with this
+ * before sending so the dashboard receives labelled rows it can render
+ * without re-computing.
+ */
+export function withCheckLabels(scorecards) {
+  if (!Array.isArray(scorecards)) return [];
+  return scorecards.map(card => ({ ...card, label: checkLabel(card) }));
+}
+
+/**
+ * Attach a `.label` field to every row in a rule-performance / rule-score
+ * array. See `withCheckLabels`.
+ */
+export function withRuleLabels(rules) {
+  if (!Array.isArray(rules)) return [];
+  return rules.map(rule => ({ ...rule, label: ruleLabel(rule) }));
+}
diff --git a/src/core/analytics-queries.js b/src/core/analytics-queries.js
index 26f012b..2403408 100644
--- a/src/core/analytics-queries.js
+++ b/src/core/analytics-queries.js
@@ -14,6 +14,39 @@ function tryParseJson(str) {
   try { return JSON.parse(str); } catch { return null; }
 }
 
+/**
+ * Resolve the tri-state `since` parameter to an ISO string or null.
+ *
+ * Reporting queries take an optional `since` opt. The contract:
+ *
+ *   - `since === undefined` (or absent): read the store's reporting baseline
+ *     meta (`analytics_baseline_ts`). Absent meta ⇒ null ⇒ no filter. This is
+ *     the reporting default — operators set the baseline once and every
+ *     dashboard widget / Markdown report widget sees the post-baseline view.
+ *   - `since === null`: explicit bypass — never filter, regardless of meta.
+ *     Reserved for engine-state callers that must see full history (case-base
+ *     auto-disable, scoreRule, server-status ops snapshot). Reporting callers
+ *     should not use this; tests use it to assert "default behaviour with no
+ *     baseline" without depending on meta state.
+ *   - `since === ''`: explicit override — use that timestamp.
+ *
+ * `store.getBaselineTs` is the analytics-store helper; absent (e.g. mock
+ * stores), the resolver degrades to "no baseline" gracefully.
+ */
+function resolveSince(store, since) {
+  if (since === null) return null;
+  if (typeof since === 'string' && since.length > 0) return since;
+  if (store && typeof store.getBaselineTs === 'function') {
+    try {
+      const baseline = store.getBaselineTs();
+      return baseline ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 /**
  * Beta-binomial posterior: given `successes` out of `total` trials
  * with prior Beta(a, b), return { mean, lower95, upper95 }.
@@ -64,35 +97,48 @@ function normalQuantile(p) {
  * @param {object} [opts]
  * @param {number} [opts.minCohort=10] - Minimum sample size for inclusion
  * @param {string} [opts.sessionId] - Limit to specific session
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array}
  */
-export function checkScorecards(store, { minCohort = MIN_COHORT, sessionId } = {}) {
+export function checkScorecards(store, { minCohort = MIN_COHORT, sessionId, since } = {}) {
+  const sinceTs = resolveSince(store, since);
   const sessionFilter = sessionId ? 'AND d.session_id = ?' : '';
+  const sinceFilter = sinceTs ? 'AND d.ts >= ?' : '';
   const params = sessionId ? [sessionId] : [];
+  if (sinceTs) params.push(sinceTs);
 
   const emittedRows = store.query(`
     SELECT d.check_name, COUNT(*) as emitted
     FROM diagnostics d
-    WHERE d.suppressed = 0 ${sessionFilter}
+    WHERE d.suppressed = 0 ${sessionFilter} ${sinceFilter}
     GROUP BY d.check_name
     HAVING COUNT(*) >= ?
   `, [...params, minCohort]);
 
   const scorecards = [];
 
+  // The `since` filter is applied to the diagnostics subquery — we want to
+  // count outcomes only for diagnostics that fall in the reporting window.
+  // The outcomes table itself has no ts column; the diagnostic's emit ts is
+  // the canonical "when this happened" for reporting purposes.
+  const outcomeSinceClause = sinceTs ? 'AND ts >= ?' : '';
+  const outcomeSinceParams = sinceTs ? [sinceTs] : [];
+
   for (const row of emittedRows) {
     const check = row.check_name;
     const emitted = row.emitted;
 
-    const outcomeParams = sessionId ? [check, sessionId] : [check];
-    const outcomeFilter = sessionId ? 'AND o.fp IN (SELECT fp FROM diagnostics WHERE session_id = ?)' : '';
+    const sessionDiagFilter = sessionId ? 'AND session_id = ?' : '';
 
     const outcomeRows = store.query(`
       SELECT o.outcome, COUNT(*) as cnt
       FROM outcomes o
-      WHERE o.fp IN (SELECT fp FROM diagnostics WHERE check_name = ?) ${outcomeFilter}
+      WHERE o.fp IN (
+        SELECT fp FROM diagnostics
+        WHERE check_name = ? ${sessionDiagFilter} ${outcomeSinceClause}
+      )
       GROUP BY o.outcome
-    `, outcomeParams);
+    `, [check, ...(sessionId ? [sessionId] : []), ...outcomeSinceParams]);
 
     const outcomes = {};
     for (const r of outcomeRows) outcomes[r.outcome] = r.cnt;
@@ -112,10 +158,13 @@ export function checkScorecards(store, { minCohort = MIN_COHORT, sessionId } = {
     const fixRows = store.query(`
       SELECT o.fix_applied, COUNT(*) as cnt
       FROM outcomes o
-      WHERE o.fp IN (SELECT fp FROM diagnostics WHERE check_name = ?)
+      WHERE o.fp IN (
+        SELECT fp FROM diagnostics
+        WHERE check_name = ? ${outcomeSinceClause}
+      )
         AND o.fix_applied IS NOT NULL
       GROUP BY o.fix_applied
-    `, [check]);
+    `, [check, ...outcomeSinceParams]);
 
     const fixCounts = {};
     for (const r of fixRows) fixCounts[r.fix_applied] = r.cnt;
@@ -129,9 +178,12 @@ export function checkScorecards(store, { minCohort = MIN_COHORT, sessionId } = {
     const collateralRow = store.queryOne(`
       SELECT AVG(o.collateral_added) as avg_collateral
       FROM outcomes o
-      WHERE o.fp IN (SELECT fp FROM diagnostics WHERE check_name = ?)
+      WHERE o.fp IN (
+        SELECT fp FROM diagnostics
+        WHERE check_name = ? ${outcomeSinceClause}
+      )
         AND o.outcome = 'regressed'
-    `, [check]);
+    `, [check, ...outcomeSinceParams]);
 
     scorecards.push({
       check,
@@ -155,15 +207,26 @@ export function checkScorecards(store, { minCohort = MIN_COHORT, sessionId } = {
  * @param {object} store - Opened analytics store
  * @param {object} [opts]
  * @param {string} [opts.sessionId] - Limit to specific session
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{bigram: [string,string], count, lift, confidence}>}
  */
-export function toolSequenceBigrams(store, { sessionId } = {}) {
-  const filter = sessionId ? 'WHERE session_id = ?' : '';
-  const params = sessionId ? [sessionId] : [];
+export function toolSequenceBigrams(store, { sessionId, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const clauses = [];
+  const params = [];
+  if (sessionId) {
+    clauses.push('session_id = ?');
+    params.push(sessionId);
+  }
+  if (sinceTs) {
+    clauses.push('ts >= ?');
+    params.push(sinceTs);
+  }
+  const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
 
   const events = store.query(`
     SELECT kind, payload FROM events
-    ${filter}
+    ${where}
     ORDER BY ts ASC
   `, params);
 
@@ -212,35 +275,48 @@ export function toolSequenceBigrams(store, { sessionId } = {}) {
  * Session-level summary: key metrics per session for cohort comparison.
  *
  * @param {object} store - Opened analytics store
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array}
  */
-export function sessionSummaries(store) {
+export function sessionSummaries(store, { since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const eventSinceWhere = sinceTs ? 'WHERE ts >= ?' : '';
+  const eventSinceAnd   = sinceTs ? 'AND ts >= ?'   : '';
+  const windowSinceAnd  = sinceTs ? 'AND w.ts_start >= ?' : '';
+
+  // Session list: sessions that had ANY event at-or-after the baseline. The
+  // session's apparent first_event is naturally clamped to the window since
+  // MIN(ts) only sees ts >= since rows.
   const sessions = store.query(`
     SELECT session_id,
            MIN(ts) as first_event,
            MAX(ts) as last_event,
            COUNT(*) as event_count
     FROM events
+    ${eventSinceWhere}
     GROUP BY session_id
     ORDER BY MIN(ts) DESC
-  `);
+  `, sinceTs ? [sinceTs] : []);
 
   return sessions.map(s => {
+    const sinceP = sinceTs ? [sinceTs] : [];
+
     const toolCalls = store.queryOne(`
       SELECT COUNT(*) as cnt FROM events
-      WHERE session_id = ? AND kind = 'tool_call'
-    `, [s.session_id]);
+      WHERE session_id = ? AND kind = 'tool_call' ${eventSinceAnd}
+    `, [s.session_id, ...sinceP]);
 
     const vcCalls = store.queryOne(`
       SELECT COUNT(*) as cnt FROM events
       WHERE session_id = ? AND kind = 'tool_call'
-        AND payload LIKE '%"tool":"validate_code"%'
-    `, [s.session_id]);
+        AND payload LIKE '%"tool":"validate_code"%' ${eventSinceAnd}
+    `, [s.session_id, ...sinceP]);
 
     const diagCount = store.queryOne(`
       SELECT COUNT(*) as cnt FROM diagnostics
-      WHERE session_id = ?
-    `, [s.session_id]);
+      WHERE session_id = ? ${eventSinceAnd}
+    `, [s.session_id, ...sinceP]);
 
     const outcomeRow = store.queryOne(`
       SELECT COUNT(*) as total,
@@ -248,14 +324,14 @@ export function sessionSummaries(store) {
              SUM(CASE WHEN outcome = 'regressed' THEN 1 ELSE 0 END) as regressed
       FROM outcomes o
       JOIN windows w ON o.window_id = w.id
-      WHERE w.session_id = ?
-    `, [s.session_id]);
+      WHERE w.session_id = ? ${windowSinceAnd}
+    `, [s.session_id, ...sinceP]);
 
     const usedIntent = store.queryOne(`
       SELECT COUNT(*) as cnt FROM events
       WHERE session_id = ? AND kind = 'tool_call'
-        AND payload LIKE '%"tool":"validate_intent"%'
-    `, [s.session_id]);
+        AND payload LIKE '%"tool":"validate_intent"%' ${eventSinceAnd}
+    `, [s.session_id, ...sinceP]);
 
     return {
       session_id: s.session_id,
@@ -278,10 +354,12 @@ export function sessionSummaries(store) {
  *
  * @param {object} store
  * @param {number} [threshold=0.3] - Mislead rate threshold
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{check, mislead_rate, recommendation}>}
  */
-export function recommendations(store, threshold = 0.3) {
-  const cards = checkScorecards(store, { minCohort: Math.max(MIN_COHORT, 5) });
+export function recommendations(store, threshold = 0.3, { since } = {}) {
+  const cards = checkScorecards(store, { minCohort: Math.max(MIN_COHORT, 5), since });
   const recs = [];
 
   for (const card of cards) {
@@ -304,17 +382,24 @@ export function recommendations(store, threshold = 0.3) {
  *
  * @param {object} store
  * @param {string} templateFp
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {{ template_fp, check, first_seen, last_seen, session_count, timeline }}
  */
-export function diagnosticJourney(store, templateFp) {
+export function diagnosticJourney(store, templateFp, { since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND ts >= ?' : '';
+  const sinceAndD = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const meta = store.queryOne(`
     SELECT check_name,
            MIN(ts) as first_seen,
            MAX(ts) as last_seen,
            COUNT(DISTINCT session_id) as session_count
     FROM diagnostics
-    WHERE template_fp = ? AND suppressed = 0
-  `, [templateFp]);
+    WHERE template_fp = ? AND suppressed = 0 ${sinceAnd}
+  `, [templateFp, ...sinceP]);
 
   if (!meta || !meta.check_name) {
     return { template_fp: templateFp, check: null, first_seen: null, last_seen: null, session_count: 0, timeline: [] };
@@ -332,9 +417,9 @@ export function diagnosticJourney(store, templateFp) {
            o.fix_applied
     FROM diagnostics d
     LEFT JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-    WHERE d.template_fp = ? AND d.suppressed = 0
+    WHERE d.template_fp = ? AND d.suppressed = 0 ${sinceAndD}
     ORDER BY d.ts ASC
-  `, [templateFp]);
+  `, [templateFp, ...sinceP]);
 
   const bySession = new Map();
   for (const row of timelineRows) {
@@ -417,9 +502,14 @@ export function diagnosticJourney(store, templateFp) {
  * @param {object} store
  * @param {object} [opts]
  * @param {number} [opts.buckets=10]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{ bucket, predicted, actual_resolution, sample_size }>}
  */
-export function confidenceCalibration(store, { buckets = 10 } = {}) {
+export function confidenceCalibration(store, { buckets = 10, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   // Post-A2: every surviving diagnostic gets a default confidence in the
   // pipeline, so dropping the `confidence IS NOT NULL` guard widens the
   // calibration sample to cover non-rule-matched diagnostics too. Rows
@@ -429,8 +519,8 @@ export function confidenceCalibration(store, { buckets = 10 } = {}) {
     SELECT d.confidence, o.outcome
     FROM diagnostics d
     JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-    WHERE d.suppressed = 0 AND d.confidence IS NOT NULL
-  `);
+    WHERE d.suppressed = 0 AND d.confidence IS NOT NULL ${sinceAnd}
+  `, sinceP);
 
   if (rows.length === 0) return [];
 
@@ -463,39 +553,51 @@ export function confidenceCalibration(store, { buckets = 10 } = {}) {
  * through rule matching, fix proposal, adoption, and resolution.
  *
  * @param {object} store
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {{ emitted, rule_matched, fix_proposed, fix_adopted_verbatim,
  *             fix_adopted_partial, fix_ignored, resolved, regressed, unchanged }}
  */
-export function fixAdoptionFunnel(store) {
+export function fixAdoptionFunnel(store, { since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  // Same `ts` column on diagnostics; use plain `ts >=` outside the EXISTS.
+  const sinceAndPlain = sinceTs ? 'AND ts >= ?' : '';
+  // Inside EXISTS subqueries we alias diagnostics as `d`.
+  const sinceAndD = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const emittedRow = store.queryOne(`
-    SELECT COUNT(*) as cnt FROM diagnostics WHERE suppressed = 0
-  `);
+    SELECT COUNT(*) as cnt FROM diagnostics
+    WHERE suppressed = 0 ${sinceAndPlain}
+  `, sinceP);
   const emitted = emittedRow?.cnt ?? 0;
 
   const ruleMatchedRow = store.queryOne(`
     SELECT COUNT(*) as cnt FROM diagnostics
-    WHERE hint_rule_id IS NOT NULL AND hint_rule_id != 'unknown' AND suppressed = 0
-  `);
+    WHERE hint_rule_id IS NOT NULL AND hint_rule_id != 'unknown' AND suppressed = 0 ${sinceAndPlain}
+  `, sinceP);
   const rule_matched = ruleMatchedRow?.cnt ?? 0;
 
   const fixProposedRow = store.queryOne(`
     SELECT COUNT(DISTINCT pf.fp) as cnt
     FROM proposed_fixes pf
     JOIN diagnostics d ON pf.fp = d.fp
-    WHERE d.suppressed = 0
-  `);
+    WHERE d.suppressed = 0 ${sinceAndD}
+  `, sinceP);
   const fix_proposed = fixProposedRow?.cnt ?? 0;
 
   // Post-A1 (dedup): outcomes has one row per (session, file, fp). A plain
   // JOIN to diagnostics on fp cross-joins by emit count — use EXISTS to
-  // keep the count at one-per-outcome-row.
+  // keep the count at one-per-outcome-row. Baseline filter goes inside the
+  // EXISTS so an outcome only counts when its diagnostic falls in the
+  // reporting window.
   const fixAdoptionRows = store.query(`
     SELECT o.fix_applied, COUNT(*) as cnt
     FROM outcomes o
     WHERE o.fix_applied IS NOT NULL
-      AND EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0)
+      AND EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0 ${sinceAndD})
     GROUP BY o.fix_applied
-  `);
+  `, sinceP);
   let fix_adopted_verbatim = 0, fix_adopted_partial = 0, fix_ignored = 0;
   for (const row of fixAdoptionRows) {
     if (row.fix_applied === 'verbatim') fix_adopted_verbatim += row.cnt;
@@ -506,9 +608,9 @@ export function fixAdoptionFunnel(store) {
   const outcomeRows = store.query(`
     SELECT o.outcome, COUNT(*) as cnt
     FROM outcomes o
-    WHERE EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0)
+    WHERE EXISTS (SELECT 1 FROM diagnostics d WHERE d.fp = o.fp AND d.suppressed = 0 ${sinceAndD})
     GROUP BY o.outcome
-  `);
+  `, sinceP);
   let resolved = 0, regressed = 0, unchanged = 0;
   for (const row of outcomeRows) {
     if (row.outcome === 'resolved') resolved += row.cnt;
@@ -534,9 +636,15 @@ export function fixAdoptionFunnel(store) {
  * commands, queries, graphql). Used by the heatmap visualization.
  *
  * @param {object} store
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{ rule_id, check, category, outcomes, resolved, regressed, effectiveness }>}
  */
-export function ruleScoresByCategory(store) {
+export function ruleScoresByCategory(store, { since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const rows = store.query(`
     SELECT d.hint_rule_id as rule_id,
            d.check_name,
@@ -544,8 +652,8 @@ export function ruleScoresByCategory(store) {
            o.outcome
     FROM diagnostics d
     JOIN outcomes o ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-    WHERE d.hint_rule_id IS NOT NULL AND d.hint_rule_id != 'unknown' AND d.suppressed = 0
-  `);
+    WHERE d.hint_rule_id IS NOT NULL AND d.hint_rule_id != 'unknown' AND d.suppressed = 0 ${sinceAnd}
+  `, sinceP);
 
   const buckets = new Map();
   for (const row of rows) {
@@ -584,19 +692,26 @@ function classifyFilePath(file) {
  * (diagnostics with no matching rule). Helps prioritize rule writing.
  *
  * @param {object} store
+ * @param {object} [opts]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{ check, unmatched_count, total_emitted, coverage_rate, avg_resolution_rate }>}
  */
-export function knowledgeGaps(store) {
+export function knowledgeGaps(store, { since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND ts >= ?' : '';
+  const sinceAndD = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const checkRows = store.query(`
     SELECT check_name,
            COUNT(*) as total_emitted,
            SUM(CASE WHEN hint_rule_id IS NULL OR hint_rule_id = 'unknown' THEN 1 ELSE 0 END) as unmatched
     FROM diagnostics
-    WHERE suppressed = 0
+    WHERE suppressed = 0 ${sinceAnd}
     GROUP BY check_name
     HAVING COUNT(*) >= 3
     ORDER BY total_emitted DESC
-  `);
+  `, sinceP);
 
   return checkRows.map(row => {
     const resRow = store.queryOne(`
@@ -604,8 +719,8 @@ export function knowledgeGaps(store) {
              SUM(CASE WHEN o.outcome = 'resolved' THEN 1 ELSE 0 END) as resolved
       FROM outcomes o
       JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-      WHERE d.check_name = ? AND d.suppressed = 0
-    `, [row.check_name]);
+      WHERE d.check_name = ? AND d.suppressed = 0 ${sinceAndD}
+    `, [row.check_name, ...sinceP]);
 
     const totalOutcomes = resRow?.total ?? 0;
     const resolvedCount = resRow?.resolved ?? 0;
@@ -640,9 +755,14 @@ export function knowledgeGaps(store) {
  * @param {object} store
  * @param {object} [opts]
  * @param {number} [opts.minEmitted=1]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array}
  */
-export function rulePerformance(store, { minEmitted = 1 } = {}) {
+export function rulePerformance(store, { minEmitted = 1, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const ruleRows = store.query(`
     SELECT d.hint_rule_id as rule_id,
            COUNT(*) as emitted,
@@ -651,9 +771,10 @@ export function rulePerformance(store, { minEmitted = 1 } = {}) {
     WHERE d.hint_rule_id IS NOT NULL
       AND d.hint_rule_id != 'unknown'
       AND d.suppressed = 0
+      ${sinceAnd}
     GROUP BY d.hint_rule_id
     HAVING COUNT(*) >= ?
-  `, [minEmitted]);
+  `, [...sinceP, minEmitted]);
 
   const scores = [];
 
@@ -663,10 +784,10 @@ export function rulePerformance(store, { minEmitted = 1 } = {}) {
       FROM outcomes o
       WHERE EXISTS (
         SELECT 1 FROM diagnostics d
-        WHERE d.fp = o.fp AND d.hint_rule_id = ? AND d.suppressed = 0
+        WHERE d.fp = o.fp AND d.hint_rule_id = ? AND d.suppressed = 0 ${sinceAnd}
       )
       GROUP BY o.outcome, o.fix_applied
-    `, [row.rule_id]);
+    `, [row.rule_id, ...sinceP]);
 
     let resolved = 0, regressed = 0, unchanged = 0, moved = 0;
     let adopted = 0, totalOutcomes = 0;
@@ -711,8 +832,19 @@ export function rulePerformance(store, { minEmitted = 1 } = {}) {
  * Rule drilldown — detailed diagnostic samples for a specific rule.
  * Returns recent instances where this rule fired, with outcomes, fix status,
  * and file distribution. Used by the dashboard drill-down panel.
+ *
+ * @param {object} store
+ * @param {string} ruleId
+ * @param {object} [opts]
+ * @param {number} [opts.limit=30]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  */
-export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) {
+export function ruleDrilldown(store, ruleId, { limit = 30, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAndD  = sinceTs ? 'AND d.ts >= ?'  : '';
+  const sinceAndD2 = sinceTs ? 'AND d2.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   // Each diagnostic row gets at most one outcome via correlated subqueries,
   // avoiding the cartesian product from a plain LEFT JOIN on fp.
   const samples = store.query(`
@@ -725,45 +857,47 @@ export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) {
            (SELECT pf.range_json FROM proposed_fixes pf WHERE pf.fp = d.fp AND pf.session_id = d.session_id LIMIT 1) as fix_range_json,
            (SELECT pf.rule_id FROM proposed_fixes pf WHERE pf.fp = d.fp AND pf.session_id = d.session_id LIMIT 1) as fix_rule_id
     FROM diagnostics d
-    WHERE d.hint_rule_id = ? AND d.suppressed = 0
+    WHERE d.hint_rule_id = ? AND d.suppressed = 0 ${sinceAndD}
     GROUP BY d.fp, d.session_id
     ORDER BY d.ts DESC
     LIMIT ?
-  `, [ruleId, limit]);
+  `, [ruleId, ...sinceP, limit]);
 
-  // File stats: count distinct fps per file, then count outcomes per fp (not per join row)
+  // File stats: count distinct fps per file, then count outcomes per fp (not per join row).
+  // Inner subqueries also filter by `since` so file-resolved/regressed counts stay
+  // consistent with the outer file emit count when the operator narrows the window.
   const fileStats = store.query(`
     SELECT d.file,
            COUNT(DISTINCT d.fp) as emitted,
            (SELECT COUNT(DISTINCT o.fp) FROM outcomes o
             JOIN diagnostics d2 ON o.fp = d2.fp
-            WHERE d2.hint_rule_id = ? AND d2.file = d.file AND o.outcome = 'resolved') as resolved,
+            WHERE d2.hint_rule_id = ? AND d2.file = d.file AND o.outcome = 'resolved' ${sinceAndD2}) as resolved,
            (SELECT COUNT(DISTINCT o.fp) FROM outcomes o
             JOIN diagnostics d2 ON o.fp = d2.fp
-            WHERE d2.hint_rule_id = ? AND d2.file = d.file AND o.outcome = 'regressed') as regressed
+            WHERE d2.hint_rule_id = ? AND d2.file = d.file AND o.outcome = 'regressed' ${sinceAndD2}) as regressed
     FROM diagnostics d
-    WHERE d.hint_rule_id = ? AND d.suppressed = 0
+    WHERE d.hint_rule_id = ? AND d.suppressed = 0 ${sinceAndD}
     GROUP BY d.file
     ORDER BY emitted DESC
     LIMIT 10
-  `, [ruleId, ruleId, ruleId]);
+  `, [ruleId, ...sinceP, ruleId, ...sinceP, ruleId, ...sinceP]);
 
   const templateStats = store.query(`
     SELECT d.template_fp,
            COUNT(DISTINCT d.fp) as count,
            (SELECT COUNT(DISTINCT o.fp) FROM outcomes o
             JOIN diagnostics d2 ON o.fp = d2.fp
-            WHERE d2.hint_rule_id = ? AND d2.template_fp = d.template_fp AND o.outcome = 'resolved') as resolved,
+            WHERE d2.hint_rule_id = ? AND d2.template_fp = d.template_fp AND o.outcome = 'resolved' ${sinceAndD2}) as resolved,
            (SELECT COUNT(DISTINCT o.fp) FROM outcomes o
             JOIN diagnostics d2 ON o.fp = d2.fp
-            WHERE d2.hint_rule_id = ? AND d2.template_fp = d.template_fp AND o.outcome = 'regressed') as regressed,
+            WHERE d2.hint_rule_id = ? AND d2.template_fp = d.template_fp AND o.outcome = 'regressed' ${sinceAndD2}) as regressed,
            MIN(d.file) as sample_file
     FROM diagnostics d
-    WHERE d.hint_rule_id = ? AND d.suppressed = 0
+    WHERE d.hint_rule_id = ? AND d.suppressed = 0 ${sinceAndD}
     GROUP BY d.template_fp
     ORDER BY count DESC
     LIMIT 10
-  `, [ruleId, ruleId, ruleId]);
+  `, [ruleId, ...sinceP, ruleId, ...sinceP, ruleId, ...sinceP]);
 
   return {
     rule_id: ruleId,
@@ -815,22 +949,27 @@ export function ruleDrilldown(store, ruleId, { limit = 30 } = {}) {
  * @param {object} store
  * @param {object} [opts]
  * @param {number} [opts.minProposed=1]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array<{
  *   rule_id, source, fix_kind,
  *   proposed, outcomes, adopted_verbatim, adopted_partial,
  *   adoption_rate, resolution_rate,
  * }>}
  */
-export function fixRulePerformance(store, { minProposed = 1 } = {}) {
+export function fixRulePerformance(store, { minProposed = 1, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND pf.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const rows = store.query(`
     SELECT pf.rule_id,
            MIN(pf.kind)  AS fix_kind,
            COUNT(*)      AS proposed
     FROM proposed_fixes pf
-    WHERE pf.rule_id IS NOT NULL
+    WHERE pf.rule_id IS NOT NULL ${sinceAnd}
     GROUP BY pf.rule_id
     HAVING COUNT(*) >= ?
-  `, [minProposed]);
+  `, [...sinceP, minProposed]);
 
   const out = [];
   for (const r of rows) {
@@ -839,10 +978,10 @@ export function fixRulePerformance(store, { minProposed = 1 } = {}) {
       FROM outcomes o
       WHERE EXISTS (
         SELECT 1 FROM proposed_fixes pf
-        WHERE pf.fp = o.fp AND pf.session_id = o.session_id AND pf.rule_id = ?
+        WHERE pf.fp = o.fp AND pf.session_id = o.session_id AND pf.rule_id = ? ${sinceAnd}
       )
       GROUP BY o.outcome, o.fix_applied
-    `, [r.rule_id]);
+    `, [r.rule_id, ...sinceP]);
 
     let resolved = 0, regressed = 0, unchanged = 0, moved = 0;
     let adopted_verbatim = 0, adopted_partial = 0, adopted_none = 0, total = 0;
diff --git a/src/core/analytics-store.js b/src/core/analytics-store.js
index 8a58207..e5e1d80 100644
--- a/src/core/analytics-store.js
+++ b/src/core/analytics-store.js
@@ -332,6 +332,52 @@ export function openAnalyticsStore(dbPath, { readonly = false, blobStore = null
     return row ? row.value : null;
   }
 
+  /**
+   * Reporting-window baseline. Operator-set checkpoint that filters every
+   * dashboard / Markdown-report query to "stats from this timestamp forward".
+   * Engine-state callers (case-base.ruleScores for syncDisabledRules,
+   * scoreRule, cac-predictor history providers, server-status disabledRules)
+   * MUST keep using full history — they pass `since: null` explicitly. Reporting
+   * callers that omit `since` resolve it via this helper.
+   *
+   * Two meta keys: `analytics_baseline_ts` (the timestamp itself) and
+   * `analytics_baseline_set_at` (when the operator set it — audit trail).
+   * Both absent ⇒ no baseline ⇒ full history (default behaviour, identical
+   * to pre-baseline releases).
+   */
+  function getBaselineTs() {
+    return getMeta('analytics_baseline_ts');
+  }
+
+  function getBaselineMeta() {
+    return {
+      baseline_ts: getMeta('analytics_baseline_ts'),
+      set_at: getMeta('analytics_baseline_set_at'),
+    };
+  }
+
+  function setBaselineTs(iso) {
+    if (iso === null || iso === undefined) {
+      clearBaseline();
+      return;
+    }
+    if (typeof iso !== 'string' || iso.length === 0) {
+      throw new TypeError(`setBaselineTs: expected ISO string or null, got ${typeof iso}`);
+    }
+    const parsed = new Date(iso);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new TypeError(`setBaselineTs: '${iso}' is not a valid date`);
+    }
+    setMeta(db, 'analytics_baseline_ts', iso);
+    setMeta(db, 'analytics_baseline_set_at', new Date().toISOString());
+  }
+
+  function clearBaseline() {
+    db.prepare('DELETE FROM meta WHERE key IN (?, ?)').run(
+      'analytics_baseline_ts', 'analytics_baseline_set_at',
+    );
+  }
+
   function stats() {
     const events = db.prepare('SELECT COUNT(*) as count FROM events').get().count;
     const diagnostics = db.prepare('SELECT COUNT(*) as count FROM diagnostics').get().count;
@@ -391,6 +437,10 @@ export function openAnalyticsStore(dbPath, { readonly = false, blobStore = null
     query,
     queryOne,
     getMeta,
+    getBaselineTs,
+    getBaselineMeta,
+    setBaselineTs,
+    clearBaseline,
     stats,
     recordPromotion,
     resolvePromotion,
diff --git a/src/core/case-base.js b/src/core/case-base.js
index 131e5d2..55f2daf 100644
--- a/src/core/case-base.js
+++ b/src/core/case-base.js
@@ -22,6 +22,40 @@ const MIN_CASES = 3;
 const RULE_DISABLE_THRESHOLD = 0.15;
 const GUARD_MIN_SAMPLES = 5;
 
+/**
+ * Resolve the tri-state `since` parameter to an ISO string or null.
+ * See analytics-queries.js:resolveSince — same contract, kept private to
+ * each module so the case-base never imports from analytics-queries (the
+ * dependency would invert the layering: case-base feeds engine state
+ * decisions; analytics-queries feeds reporting).
+ *
+ * Reporting callers in case-base (retrieveCases*, suggestedRules,
+ * synthesizeGuardPredicate, ruleScores via /api/analytics/rule-scores)
+ * pass `since` and let it auto-resolve to the operator baseline.
+ *
+ * Engine-state callers (`syncDisabledRules` in server.js,
+ * `disabled_rules` in server-status.js, `resolveProbation` here) pass
+ * `since: null` explicitly so a baseline operator-set on the dashboard
+ * never narrows the data the auto-disable / probation logic sees.
+ *
+ * `scoreRule` is the live confidence-adjustment path (called per emit
+ * from rules/engine.js) — it deliberately has no `since` parameter at
+ * all; case-base scoring must always see full history.
+ */
+function resolveSince(store, since) {
+  if (since === null) return null;
+  if (typeof since === 'string' && since.length > 0) return since;
+  if (store && typeof store.getBaselineTs === 'function') {
+    try {
+      const baseline = store.getBaselineTs();
+      return baseline ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 /**
  * F1: Retrieve cases for a diagnostic template.
  *
@@ -33,13 +67,19 @@ const GUARD_MIN_SAMPLES = 5;
  * @param {string} templateFp - Template fingerprint
  * @param {object} [opts]
  * @param {number} [opts.minCases=3] - Minimum cases to include a fix
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {CaseResult}
  */
-export function retrieveCases(store, check, templateFp, { minCases = MIN_CASES } = {}) {
+export function retrieveCases(store, check, templateFp, { minCases = MIN_CASES, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND ts >= ?' : '';
+  const sinceAndD = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const totalRow = store.queryOne(`
     SELECT COUNT(*) as cnt FROM diagnostics
-    WHERE check_name = ? AND template_fp = ? AND suppressed = 0
-  `, [check, templateFp]);
+    WHERE check_name = ? AND template_fp = ? AND suppressed = 0 ${sinceAnd}
+  `, [check, templateFp, ...sinceP]);
 
   const total = totalRow?.cnt ?? 0;
   if (total === 0) return { check, template_fp: templateFp, total: 0, cases: [] };
@@ -48,10 +88,10 @@ export function retrieveCases(store, check, templateFp, { minCases = MIN_CASES }
     SELECT o.outcome, o.fix_applied, o.collateral_added, COUNT(*) as cnt
     FROM outcomes o
     JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-    WHERE d.check_name = ? AND d.template_fp = ?
+    WHERE d.check_name = ? AND d.template_fp = ? ${sinceAndD}
     GROUP BY o.outcome, o.fix_applied
     ORDER BY cnt DESC
-  `, [check, templateFp]);
+  `, [check, templateFp, ...sinceP]);
 
   const byFix = new Map();
   for (const row of outcomeRows) {
@@ -83,16 +123,29 @@ export function retrieveCases(store, check, templateFp, { minCases = MIN_CASES }
 
 /**
  * F1 (batch): Retrieve top cases for all templates of a given check.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.minCases=3]
+ * @param {number} [opts.limit=20]
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  */
-export function retrieveCasesByCheck(store, check, { minCases = MIN_CASES, limit = 20 } = {}) {
+export function retrieveCasesByCheck(store, check, { minCases = MIN_CASES, limit = 20, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const templates = store.query(`
     SELECT DISTINCT template_fp FROM diagnostics
-    WHERE check_name = ? AND template_fp IS NOT NULL AND suppressed = 0
-  `, [check]);
+    WHERE check_name = ? AND template_fp IS NOT NULL AND suppressed = 0 ${sinceAnd}
+  `, [check, ...sinceP]);
 
   const results = [];
   for (const { template_fp } of templates) {
-    const caseResult = retrieveCases(store, check, template_fp, { minCases });
+    // Forward the *resolved* timestamp (or null) so the inner call doesn't
+    // re-read meta. Without this, an explicit since='ISO' here would still
+    // propagate as undefined inside retrieveCases and pull from meta — which
+    // is the wrong source when the operator is overriding the default.
+    const caseResult = retrieveCases(store, check, template_fp, { minCases, since: sinceTs });
     if (caseResult.cases.length > 0) results.push(caseResult);
   }
 
@@ -114,12 +167,29 @@ export function retrieveCasesByCheck(store, check, { minCases = MIN_CASES, limit
  * registered rule, so "disabling" them has no effect and they shouldn't count
  * toward promotion/probation decisions.
  *
+ * `since` contract — IMPORTANT for engine-state callers:
+ *   - server.js `syncDisabledRules` and tools/server-status.js's
+ *     `disabled_rules` snapshot pass `since: null` explicitly so the
+ *     operator-set reporting baseline cannot narrow what auto-disable
+ *     considers. A sample of "since baseline" might be too small to
+ *     trigger correctly; full history is required for stable engine state.
+ *   - http-server.js endpoints (rule-scores, engine-map) omit `since`
+ *     so they default to the resolved meta baseline — operators viewing
+ *     the dashboard see the post-baseline view.
+ *
  * @param {object} store
  * @param {object} [opts]
  * @param {number} [opts.minEmitted=5] - Minimum emissions to include
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
+ *   ENGINE-STATE callers must pass `null` to bypass the meta baseline.
  * @returns {Array}
  */
-export function ruleScores(store, { minEmitted = 5 } = {}) {
+export function ruleScores(store, { minEmitted = 5, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceAndD = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const ruleRows = store.query(`
     SELECT d.hint_rule_id as rule_id,
            COUNT(*) as emitted,
@@ -129,9 +199,10 @@ export function ruleScores(store, { minEmitted = 5 } = {}) {
       AND d.hint_rule_id != 'unknown'
       AND d.hint_rule_id NOT LIKE '%.unmatched'
       AND d.suppressed = 0
+      ${sinceAnd}
     GROUP BY d.hint_rule_id
     HAVING COUNT(*) >= ?
-  `, [minEmitted]);
+  `, [...sinceP, minEmitted]);
 
   const scores = [];
 
@@ -140,11 +211,11 @@ export function ruleScores(store, { minEmitted = 5 } = {}) {
       SELECT o.outcome, o.fix_applied, COUNT(*) as cnt
       FROM outcomes o
       WHERE o.fp IN (
-        SELECT DISTINCT fp FROM diagnostics
-        WHERE hint_rule_id = ? AND suppressed = 0
+        SELECT DISTINCT d.fp FROM diagnostics d
+        WHERE d.hint_rule_id = ? AND d.suppressed = 0 ${sinceAndD}
       )
       GROUP BY o.outcome, o.fix_applied
-    `, [row.rule_id]);
+    `, [row.rule_id, ...sinceP]);
 
     let resolved = 0, regressed = 0, unchanged = 0, moved = 0;
     let adopted = 0, totalOutcomes = 0;
@@ -244,18 +315,23 @@ export function scoreRule(store, ruleId, templateFp) {
  * @param {object} [opts]
  * @param {number} [opts.minCases=5] - Minimum outcome count
  * @param {number} [opts.minResolutionRate=0.6] - Minimum resolution rate
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {Array}
  */
-export function suggestedRules(store, existingRuleChecks = new Set(), { minCases = 5, minResolutionRate = 0.6 } = {}) {
+export function suggestedRules(store, existingRuleChecks = new Set(), { minCases = 5, minResolutionRate = 0.6, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND d.ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const candidates = store.query(`
     SELECT d.check_name, d.template_fp,
            COUNT(DISTINCT d.fp) as emitted,
            GROUP_CONCAT(DISTINCT d.hint_rule_id) as rule_ids
     FROM diagnostics d
-    WHERE d.suppressed = 0 AND d.template_fp IS NOT NULL
+    WHERE d.suppressed = 0 AND d.template_fp IS NOT NULL ${sinceAnd}
     GROUP BY d.check_name, d.template_fp
     HAVING COUNT(DISTINCT d.fp) >= ?
-  `, [minCases]);
+  `, [...sinceP, minCases]);
 
   const suggestions = [];
 
@@ -267,9 +343,9 @@ export function suggestedRules(store, existingRuleChecks = new Set(), { minCases
       SELECT o.outcome, o.fix_applied, COUNT(*) as cnt
       FROM outcomes o
       JOIN diagnostics d ON o.fp = d.fp AND o.session_id = d.session_id AND o.file = d.file
-      WHERE d.check_name = ? AND d.template_fp = ?
+      WHERE d.check_name = ? AND d.template_fp = ? ${sinceAnd}
       GROUP BY o.outcome, o.fix_applied
-    `, [c.check_name, c.template_fp]);
+    `, [c.check_name, c.template_fp, ...sinceP]);
 
     let resolved = 0, total = 0;
     let bestFix = null;
@@ -290,11 +366,15 @@ export function suggestedRules(store, existingRuleChecks = new Set(), { minCases
     const resRate = resolved / total;
     if (resRate < minResolutionRate) continue;
 
+    // The sample diagnostic must come from the same window the suggestion
+    // was derived from; if the operator is viewing post-baseline only, the
+    // sample file should reflect that window too.
+    const sampleSinceAnd = sinceTs ? 'AND ts >= ?' : '';
     const sampleDiag = store.queryOne(`
       SELECT file, check_name, fp FROM diagnostics
-      WHERE check_name = ? AND template_fp = ? AND suppressed = 0
+      WHERE check_name = ? AND template_fp = ? AND suppressed = 0 ${sampleSinceAnd}
       ORDER BY ts DESC LIMIT 1
-    `, [c.check_name, c.template_fp]);
+    `, [c.check_name, c.template_fp, ...sinceP]);
 
     suggestions.push({
       check: c.check_name,
@@ -331,15 +411,20 @@ export function suggestedRules(store, existingRuleChecks = new Set(), { minCases
  * @param {string} templateFp - Template fingerprint
  * @param {object} [opts]
  * @param {number} [opts.minSamples=5] - Minimum samples to infer a guard
+ * @param {string|null} [opts.since] - Reporting baseline. See resolveSince().
  * @returns {object} JSON `when` object for promoted rules
  */
-export function synthesizeGuardPredicate(store, check, templateFp, { minSamples = GUARD_MIN_SAMPLES } = {}) {
+export function synthesizeGuardPredicate(store, check, templateFp, { minSamples = GUARD_MIN_SAMPLES, since } = {}) {
+  const sinceTs = resolveSince(store, since);
+  const sinceAnd = sinceTs ? 'AND ts >= ?' : '';
+  const sinceP = sinceTs ? [sinceTs] : [];
+
   const when = {};
 
   const fileRows = store.query(`
     SELECT DISTINCT file FROM diagnostics
-    WHERE check_name = ? AND template_fp = ? AND suppressed = 0
-  `, [check, templateFp]);
+    WHERE check_name = ? AND template_fp = ? AND suppressed = 0 ${sinceAnd}
+  `, [check, templateFp, ...sinceP]);
 
   if (fileRows.length >= minSamples) {
     const types = fileRows.map(r => classifyFileType(r.file));
@@ -354,7 +439,8 @@ export function synthesizeGuardPredicate(store, check, templateFp, { minSamples
     WHERE kind = 'validator_emit'
     AND json_extract(payload, '$.check') = ?
     AND json_extract(payload, '$.template_fp') = ?
-  `, [check, templateFp]);
+    ${sinceAnd}
+  `, [check, templateFp, ...sinceP]);
 
   const paramSamples = [];
   for (const row of eventRows) {
diff --git a/src/core/diagnostic-pipeline.js b/src/core/diagnostic-pipeline.js
index c29f476..bf89a6c 100644
--- a/src/core/diagnostic-pipeline.js
+++ b/src/core/diagnostic-pipeline.js
@@ -6,6 +6,10 @@
  * and is documented with its purpose and ordering dependencies.
  *
  * ORDERING CONTRACT:
+ *   0a. suppressLspKnownFalsePositives — must run FIRST (after raw user suppressions) so
+ *       downstream enrichment, fix generation, and the must_fix_before_write gate
+ *       never see the spurious LSP error. Currently covers the pos-cli LSP
+ *       "Syntax is not supported" regression on `assign x = a  b`.
  *   1. suppressDocParams               — must run before Shopify elevation (doc params may look like Shopify objects)
  *   2. suppressUnusedDocParams         — depends on content, independent of other filters
  *   3. elevateShopify                  — must run after enrichment (needs .suggestion field)
@@ -47,6 +51,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
+import { toLiquidHtmlAST } from '@platformos/liquid-html-parser';
 import { getKnownModulesMissingDocs } from './knowledge-loader.js';
 import { buildAssetIndex, resolveAssetPath } from './asset-index.js';
 import { buildTranslationIndex } from './translation-index.js';
@@ -103,6 +108,12 @@ export function runDiagnosticPipeline(result, opts) {
     traceStep('userSuppressions', () => applyUserSuppressions(result, filePath, projectDir));
   }
 
+  // 0a. Suppress known pos-cli LSP false positives. Currently covers the
+  //     "Syntax is not supported" regression on `assign x = a  b` boolean
+  //     comparisons. Runs first so downstream enrichment, fix generation,
+  //     and the must_fix_before_write gate never see the spurious error.
+  traceStep('suppressLspKnownFalsePositives', () => suppressLspKnownFalsePositives(result, content));
+
   // 1. Suppress UndefinedObject for declared @param names
   if (docParamNames.size > 0) {
     traceStep('suppressDocParams', () => suppressDocParams(result, docParamNames));
@@ -188,9 +199,14 @@ export function runDiagnosticPipeline(result, opts) {
     traceStep('verifyTranslationKeysOnDisk', () => verifyTranslationKeysOnDisk(result, projectDir));
   }
 
-  // 14. Verify MissingPage against filesystem
+  // 14. Verify MissingPage against filesystem. The file under validation is
+  //     passed as an overlay so its in-memory frontmatter (`slug:`, `method:`)
+  //     contributes to the route index — fixes the self-page case where an
+  //     agent validating `app/views/pages/index.liquid` with `method: post`
+  //     in-memory would otherwise see a stale MissingPage warning for the
+  //     very route this page is about to serve.
   if (projectDir) {
-    traceStep('verifyPageRoutesOnDisk', () => verifyPageRoutesOnDisk(result, projectDir));
+    traceStep('verifyPageRoutesOnDisk', () => verifyPageRoutesOnDisk(result, projectDir, { filePath, content }));
   }
 
   // 15. Verify OrphanedPartial against filesystem
@@ -214,6 +230,80 @@ export function runDiagnosticPipeline(result, opts) {
 
 // ── Individual filters ──────────────────────────────────────────────────────
 
+/**
+ * Suppress known pos-cli LSP false positives.
+ *
+ * Currently covers ONE pattern: `LiquidHTMLSyntaxError` with the generic
+ * upstream message `Syntax is not supported`, fired by pos-cli's LSP on a
+ * boolean comparison inside an `assign` tag (e.g. `assign object.valid = c == empty`,
+ * `assign x = 1 == 1`). The platformOS Liquid parser
+ * (`@platformos/liquid-html-parser`, the same package the runtime parser is
+ * derived from) accepts this syntax, and `pos-cli check run` reports no
+ * offenses on it. Only the LSP rejects it — a stand-alone regression in the
+ * LSP's expression parser, not in the language.
+ *
+ * Without this suppression, agents are forced to rewrite valid Liquid
+ * (typically by lowering `assign x = a == b` to a four-line if/else) just to
+ * pass the must_fix_before_write gate. Worse, the diagnostic message
+ * "Syntax is not supported" gives no actionable hint, so agents iterate
+ * blindly until something passes.
+ *
+ * Suppression criteria — all must hold:
+ *   1. The diagnostic check is `LiquidHTMLSyntaxError`.
+ *   2. The message matches the exact upstream phrasing `Syntax is not supported`
+ *      (case-insensitive). Other LiquidHTMLSyntaxError messages — unclosed
+ *      blocks, malformed tag arguments, etc. — point at real bugs and stay.
+ *   3. The file parses cleanly under the strict mode of the platformOS parser.
+ *      A genuine syntax error elsewhere in the file would fail strict parse,
+ *      and we leave every diagnostic in place to avoid masking it.
+ *
+ * When all three hold, the matching diagnostics are removed and a single
+ * `pos-supervisor:LspSyntaxFalsePositiveSuppressed` info diagnostic is
+ * emitted naming the lines so the agent can audit the suppression.
+ */
+function suppressLspKnownFalsePositives(result, content) {
+  const matches = (d) =>
+    d.check === 'LiquidHTMLSyntaxError' &&
+    typeof d.message === 'string' &&
+    /^Syntax is not supported$/i.test(d.message.trim());
+
+  const candidates = [
+    ...result.errors.filter(matches),
+    ...result.warnings.filter(matches),
+  ];
+  if (candidates.length === 0) return;
+
+  // Strict parse — no tolerant flag — is the gate. If the platformOS parser
+  // rejects the file, there IS a genuine syntax error and we must not
+  // suppress LSP errors that may be the agent's only signal.
+  let parsesCleanly;
+  try {
+    toLiquidHtmlAST(content);
+    parsesCleanly = true;
+  } catch {
+    parsesCleanly = false;
+  }
+  if (!parsesCleanly) return;
+
+  const removeSet = new Set(candidates);
+  result.errors = result.errors.filter(d => !removeSet.has(d));
+  result.warnings = result.warnings.filter(d => !removeSet.has(d));
+
+  const lines = candidates
+    .map(d => d.line)
+    .filter(n => n != null);
+  result.infos.push({
+    check: 'pos-supervisor:LspSyntaxFalsePositiveSuppressed',
+    severity: 'info',
+    message:
+      `Suppressed ${candidates.length} LiquidHTMLSyntaxError("Syntax is not supported") ` +
+      `diagnostic(s)${lines.length ? ` on line(s) ${lines.join(', ')}` : ''} — ` +
+      `the platformOS parser (@platformos/liquid-html-parser) accepts the file. ` +
+      `This is a known pos-cli LSP regression, most often triggered by a boolean ` +
+      `comparison inside \`assign\` (e.g. \`assign x = a == b\`).`,
+  });
+}
+
 function applyUserSuppressions(result, filePath, projectDir) {
   const suppressFile = join(projectDir, '.pos-supervisor-ignore.yml');
   if (!existsSync(suppressFile)) return;
@@ -818,11 +908,11 @@ function verifyMissingAssets(result, projectDir) {
  *     link to a POST-only route) and the agent needs to see it.
  *   - route not served at all → diagnostic stands.
  */
-function verifyPageRoutesOnDisk(result, projectDir) {
+function verifyPageRoutesOnDisk(result, projectDir, currentFile = null) {
   const candidates = [...result.errors, ...result.warnings].filter(d => d.check === 'MissingPage');
   if (candidates.length === 0) return;
 
-  const index = buildPageRouteIndex(projectDir);
+  const index = buildPageRouteIndex(projectDir, currentFile);
   if (index.routes.size === 0) return;
 
   const suppressed = new Set();
diff --git a/src/core/page-route-index.js b/src/core/page-route-index.js
index 42aae1f..b1f661f 100644
--- a/src/core/page-route-index.js
+++ b/src/core/page-route-index.js
@@ -27,15 +27,38 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { isAbsolute, join, relative, sep } from 'node:path';
 
 const PAGES_SUBDIR = 'app/views/pages';
 
 /**
+ * Build a route → methods index from the project's pages directory.
+ *
+ * The optional `overlay` represents the file CURRENTLY under validation. Its
+ * in-memory content is used in place of the on-disk version (or in addition
+ * to, if the file does not yet exist on disk). This is load-bearing for the
+ * self-page case: when the agent runs validate_code on `app/views/pages/index.liquid`
+ * with `method: post` in-memory frontmatter while disk still has no method
+ * declaration, the LSP fires `MissingPage` for route `/` (POST). The on-disk
+ * scan alone would not see the in-memory frontmatter and the false positive
+ * would survive verification — even though, the moment the agent writes,
+ * the route IS served.
+ *
+ * Overlay rules:
+ *   - filePath may be relative (resolved against projectDir) or absolute.
+ *   - Only files under `app/views/pages/` are considered. A non-page overlay
+ *     (e.g., a partial under validation) is ignored — the index covers pages
+ *     only.
+ *   - The overlay is treated as the source of truth for that one file. When
+ *     the same path also exists on disk, the disk read is skipped and the
+ *     overlay frontmatter wins. When the path does not exist on disk yet,
+ *     the overlay adds a new entry to the index.
+ *
  * @param {string} projectDir
+ * @param {{ filePath: string, content: string } | null} [overlay]
  * @returns {{ routes: Map> }}
  */
-export function buildPageRouteIndex(projectDir) {
+export function buildPageRouteIndex(projectDir, overlay = null) {
   const routes = new Map();
   if (!projectDir) return { routes };
 
@@ -58,10 +81,31 @@ export function buildPageRouteIndex(projectDir) {
     }
   }
 
+  // Resolve the overlay (if any) to an absolute path under the pages root.
+  // Overlays outside `app/views/pages/` are ignored — the route index covers
+  // pages only, and partials/layouts/assets cannot serve a route.
+  let overlayAbs = null;
+  if (
+    overlay &&
+    typeof overlay.filePath === 'string' &&
+    typeof overlay.content === 'string' &&
+    /\.liquid$/.test(overlay.filePath)
+  ) {
+    const abs = isAbsolute(overlay.filePath) ? overlay.filePath : join(projectDir, overlay.filePath);
+    if (abs === rootAbs || abs.startsWith(rootAbs + sep)) {
+      overlayAbs = abs;
+      if (!files.includes(abs)) files.push(abs);
+    }
+  }
+
   for (const abs of files) {
     let raw;
-    try { raw = readFileSync(abs, 'utf8'); }
-    catch { continue; }
+    if (abs === overlayAbs) {
+      raw = overlay.content;
+    } else {
+      try { raw = readFileSync(abs, 'utf8'); }
+      catch { continue; }
+    }
 
     const rel = relative(rootAbs, abs).split(sep).join('/');
     const { slug, method } = extractFrontmatter(raw);
diff --git a/src/core/rules/MissingPartial.js b/src/core/rules/MissingPartial.js
index b9a6f74..09c8df9 100644
--- a/src/core/rules/MissingPartial.js
+++ b/src/core/rules/MissingPartial.js
@@ -7,6 +7,12 @@
  *   20 — file_exists: target exists on disk but LSP still flags → guidance
  *   30 — suggest_nearest: did-you-mean via Levenshtein on reachable partials
  *   40 — create_file: generate create_file fix with scaffold
+ * 1000 — default: catch-all that fires when none of the above guards matched
+ *        (missing extractor params, unrecognised path shape, etc.). Without
+ *        this rule the diagnostic would land as `MissingPartial.unmatched` and
+ *        the agent would see the bare LSP message — every `.unmatched` row in
+ *        the dashboard analytics. The default is intentionally guidance-only,
+ *        confidence 0.5, so it never preempts a more specific rule.
  */
 import { classifyPath, nearestByLevenshtein, partialNames, partialsReachableFrom } from './queries.js';
 import {
@@ -286,6 +292,47 @@ export const rules = [
       };
     },
   },
+
+  // Last-resort catch-all. Fires when none of the specialised guards above
+  // matched — typically because the LSP message did not parse into a
+  // `params.partial` (an upstream message-shape change), or because the path
+  // shape (`type` from classifyPath) did not fit any existing rule. Hint
+  // surfaces the three canonical resolutions with no false specifics, so the
+  // agent gets actionable guidance instead of `.unmatched` + bare LSP text.
+  {
+    id: 'MissingPartial.default',
+    check: 'MissingPartial',
+    priority: 1000,
+    when: () => true,
+    apply: (diag) => {
+      const name = diag.params?.partial ?? null;
+      const ref = name ? `\`${name}\`` : 'this reference';
+      return {
+        rule_id: 'MissingPartial.default',
+        hint_md:
+          `${ref} does not resolve to any partial, command, or query in the project. ` +
+          `Three canonical resolutions:\n` +
+          `  • **Typo** — fix the path in the \`{% render %}\` / \`{% function %}\` tag.\n` +
+          `  • **Missing file** — create the target. Partials live under \`app/views/partials/\`, ` +
+          `commands under \`app/lib/commands/\`, queries under \`app/lib/queries/\`.\n` +
+          `  • **Wrong prefix** — \`function\` paths resolve from \`app/lib/\`, so \`lib/commands/X\` ` +
+          `expands to \`app/lib/lib/commands/X\` and never resolves. Drop the leading \`lib/\`.\n\n` +
+          `Run \`project_map\` to enumerate the partials, commands, and queries this project actually has.`,
+        fixes: [{
+          type: 'guidance',
+          description: name
+            ? `Verify the path \`${name}\` against \`project_map\` output, then either correct the typo, drop a leading \`lib/\` if present, or create the file at the canonical location.`
+            : `Run \`project_map\` to enumerate available partials, commands, and queries; reconcile the failing reference against the live list.`,
+        }],
+        confidence: 0.5,
+        see_also: {
+          tool: 'project_map',
+          args: {},
+          reason: 'project_map lists every partial, command, and query the project serves — the authoritative source for resolving a missing reference.',
+        },
+      };
+    },
+  },
 ];
 
 /**
diff --git a/src/core/rules/TranslationKeyExists.js b/src/core/rules/TranslationKeyExists.js
index dcf072c..c411133 100644
--- a/src/core/rules/TranslationKeyExists.js
+++ b/src/core/rules/TranslationKeyExists.js
@@ -2,14 +2,18 @@
  * TranslationKeyExists rules — translation key not found.
  *
  * Priority order (first match wins):
- *   5  — array_index_misuse: agent wrote `key[0]` / `key[1]` etc.
- *        platformOS translations cannot be subscripted with `[N]` —
- *        the modern pattern is `{% assign items = 'key' | t %}` then
- *        iterate with `{% for item in items %}`. Owns this case so the
- *        downstream Levenshtein rule never produces a misleading
- *        "did you mean en.key.items" suggestion.
- *   10 — suggest_nearest: key is close to an existing translation key
- *   20 — create_key:      suggest adding the key to translation file
+ *   5    — array_index_misuse: agent wrote `key[0]` / `key[1]` etc.
+ *          platformOS translations cannot be subscripted with `[N]` —
+ *          the modern pattern is `{% assign items = 'key' | t %}` then
+ *          iterate with `{% for item in items %}`. Owns this case so the
+ *          downstream Levenshtein rule never produces a misleading
+ *          "did you mean en.key.items" suggestion.
+ *   10   — suggest_nearest: key is close to an existing translation key
+ *   20   — create_key:      suggest adding the key to translation file
+ *  1000  — default:         catch-all for cases where extraction failed and
+ *          no specialised rule's guard matched. Without this, the diagnostic
+ *          would land as `TranslationKeyExists.unmatched` and the agent would
+ *          see the bare LSP message.
  *
  * Defensive design: every `[N]`-aware gate looks at BOTH `params.key` and
  * `diag.message`. If the extractor ever drifts (LSP message shape change,
@@ -156,4 +160,39 @@ export const rules = [
       };
     },
   },
+
+  // Last-resort catch-all. Triggered when the LSP emits a translation-key
+  // diagnostic whose message did not yield a `params.key` (extractor drift,
+  // unrecognised wording). Emits a generic but typed hint so the row is
+  // attributed to a real rule_id rather than `.unmatched`.
+  {
+    id: 'TranslationKeyExists.default',
+    check: 'TranslationKeyExists',
+    priority: 1000,
+    when: () => true,
+    apply: (diag) => {
+      const key = diag.params?.key ?? null;
+      const ref = key ? `\`${key}\`` : 'this translation key';
+      return {
+        rule_id: 'TranslationKeyExists.default',
+        hint_md:
+          `${ref} is not defined in any translation file under \`app/translations/\`. ` +
+          `Two valid resolutions:\n` +
+          `  • **Typo** — correct the key in the \`{{ '...' | t }}\` call site. ` +
+          `Do NOT prepend the locale (\`${DEFAULT_LOCALE}.\`) — \`| t\` resolves the active ` +
+          `locale automatically.\n` +
+          `  • **Missing key** — add it to \`app/translations/${DEFAULT_LOCALE}.yml\` under the ` +
+          `\`${DEFAULT_LOCALE}:\` root, mirroring the dot-path of the call.\n\n` +
+          `If you're mid-feature and the key is part of the plan but not yet on disk, pass ` +
+          `\`pending_translations=[]\` to validate_code so this stops firing while you write it.`,
+        fixes: [{
+          type: 'guidance',
+          description: key
+            ? `Reconcile \`${key}\` with \`app/translations/${DEFAULT_LOCALE}.yml\`: either fix the call-site spelling or add the key under the \`${DEFAULT_LOCALE}:\` root.`
+            : `Inspect \`app/translations/${DEFAULT_LOCALE}.yml\` and reconcile the failing key.`,
+        }],
+        confidence: 0.5,
+      };
+    },
+  },
 ];
diff --git a/src/core/rules/UndefinedObject.js b/src/core/rules/UndefinedObject.js
index 4583677..fdd38e0 100644
--- a/src/core/rules/UndefinedObject.js
+++ b/src/core/rules/UndefinedObject.js
@@ -2,9 +2,15 @@
  * UndefinedObject rules — variable not defined in current scope.
  *
  * Priority order:
- *   10 — shopify_object: Shopify theme object detected → migration guidance
- *   20 — context_prefix: bare variable in page needs context. prefix
- *   30 — declare_param: partial/command/query needs @param declaration
+ *    10 — shopify_object:   Shopify theme object detected → migration guidance
+ *    20 — context_prefix:   bare variable in page needs context. prefix
+ *    30 — declare_param:    partial/command/query needs @param declaration
+ *   100 — generic:          variable name extracted but no specialised rule applies
+ *  1000 — default:          catch-all for the case where extraction failed
+ *         (LSP message shape change, etc.). Without this rule the diagnostic
+ *         would land as `UndefinedObject.unmatched`. Confidence is intentionally
+ *         lower than `.generic` so analytics treat it as a coverage signal, not
+ *         an authoritative answer.
  */
 import { isShopifyObject, getShopifyObject, getCheckKnowledge } from '../knowledge-loader.js';
 
@@ -135,4 +141,34 @@ export const rules = [
       };
     },
   },
+
+  // Last-resort catch-all. Reached only when `.generic`'s extraction guard
+  // failed — the LSP emitted an UndefinedObject whose message did not match
+  // the documented shape. Surfaces a diagnostic that names "an undefined
+  // variable" without pretending we know which one.
+  {
+    id: 'UndefinedObject.default',
+    check: 'UndefinedObject',
+    priority: 1000,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'UndefinedObject.default',
+      hint_md:
+        `An undefined variable is referenced. Read the upstream message — it names the variable. ` +
+        `Three canonical resolutions:\n` +
+        `  • **In a page** — bare names like \`params\`, \`session\`, \`current_user\` need ` +
+        `the \`context.\` prefix.\n` +
+        `  • **In a partial / command / query** — declare the variable as a \`{% doc %} ` +
+        `@param {}  {% enddoc %}\` and have the caller pass it.\n` +
+        `  • **Local computation** — assign before use: \`{% assign x = ... %}\` / ` +
+        `\`{% graphql x = ... %}\` / \`{% function x = ... %}\`.`,
+      fixes: [{
+        type: 'guidance',
+        description:
+          `Re-read the upstream message for the variable name, then either prefix with \`context.\`, ` +
+          `declare as a \`@param\`, or assign before use depending on where the reference lives.`,
+      }],
+      confidence: 0.4,
+    }),
+  },
 ];
diff --git a/src/core/rules/UnknownFilter.js b/src/core/rules/UnknownFilter.js
index 3f08942..676423f 100644
--- a/src/core/rules/UnknownFilter.js
+++ b/src/core/rules/UnknownFilter.js
@@ -2,10 +2,13 @@
  * UnknownFilter rules — filter does not exist in platformOS Liquid.
  *
  * Priority order:
- *   10 — tag_confusion: filter name is actually a tag
- *   20 — shopify_filter: Shopify-specific filter detected
- *   30 — suggest_nearest: did-you-mean via filters index
- *   40 — generic: fallback hint
+ *    10 — tag_confusion:   filter name is actually a tag
+ *    20 — shopify_filter:  Shopify-specific filter detected
+ *    30 — suggest_nearest: did-you-mean via filters index
+ *   100 — generic:         filter name extracted but no specialised rule applies
+ *  1000 — default:         catch-all for the case where extraction failed.
+ *         Stops the diagnostic from landing as `UnknownFilter.unmatched` and
+ *         gives the agent a typed hint regardless of upstream message shape.
  */
 import { isShopifyFilter, getShopifyFilter } from '../knowledge-loader.js';
 
@@ -135,4 +138,36 @@ export const rules = [
       };
     },
   },
+
+  // Last-resort catch-all. Reached only when `.generic`'s extraction guard
+  // failed — the LSP emitted an UnknownFilter whose message did not match
+  // the documented "Unknown filter ''" shape. Hint stays generic but
+  // is enough to direct the agent at the lookup tool and the
+  // platformOS-vs-Shopify distinction.
+  {
+    id: 'UnknownFilter.default',
+    check: 'UnknownFilter',
+    priority: 1000,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'UnknownFilter.default',
+      hint_md:
+        `An unknown filter is referenced. Read the upstream message — it names the filter. ` +
+        `Two canonical resolutions:\n` +
+        `  • **Typo** — fix the filter name. Use \`lookup\` (completions mode) at the filter position ` +
+        `to see what platformOS actually ships.\n` +
+        `  • **Shopify-only filter** — platformOS does not have Shopify's \`money\`, \`img_url\`, ` +
+        `\`link_to\` family. Replace with the platformOS equivalent or restructure the template.\n\n` +
+        `Tags and filters are syntactically distinct: \`{% tag ... %}\` vs \`| filter\`. ` +
+        `If the name is actually a tag, switch to block syntax.`,
+      fixes: [{
+        type: 'guidance',
+        description:
+          `Re-read the upstream message for the filter name, then look it up via \`lookup\` ` +
+          `(completions mode) at the filter position. If it's Shopify-specific, find the ` +
+          `platformOS equivalent or rewrite the expression.`,
+      }],
+      confidence: 0.4,
+    }),
+  },
 ];
diff --git a/src/core/rules/UnknownProperty.js b/src/core/rules/UnknownProperty.js
index d178ef3..d41c785 100644
--- a/src/core/rules/UnknownProperty.js
+++ b/src/core/rules/UnknownProperty.js
@@ -2,9 +2,13 @@
  * UnknownProperty rules — property does not exist on the given object.
  *
  * Priority order:
- *   10 — schema_property: object is a known schema table → suggest valid properties
- *   20 — context_property: object is context.* → list valid sub-properties
- *   100 — generic: fallback hint
+ *    10 — schema_property:  object is a known schema table → suggest valid properties
+ *    20 — context_property: object is context.* → list valid sub-properties
+ *   100 — generic:          property + object extracted but no specialised rule applies
+ *  1000 — default:          catch-all for the case where extraction failed —
+ *         the LSP message did not yield both `params.property` AND
+ *         `params.object`. Stops the diagnostic from landing as
+ *         `UnknownProperty.unmatched`.
  */
 import { nearestByLevenshtein } from './queries.js';
 
@@ -103,4 +107,35 @@ export const rules = [
       };
     },
   },
+
+  // Last-resort catch-all. Reached when `.generic`'s extraction guard failed
+  // (object name OR property name absent from the parsed message). Hint
+  // stays generic and points at \`lookup\` so the agent can still recover
+  // without the symbol names.
+  {
+    id: 'UnknownProperty.default',
+    check: 'UnknownProperty',
+    priority: 1000,
+    when: () => true,
+    apply: () => ({
+      rule_id: 'UnknownProperty.default',
+      hint_md:
+        `A property reference does not resolve on its host object. Read the upstream message — ` +
+        `it names both the object and the property. Three canonical resolutions:\n` +
+        `  • **Typo** — fix the property name on the call site.\n` +
+        `  • **Schema property** — if the object is a record from a schema, verify the property ` +
+        `against \`app/schema/.yml\`. Use \`lookup\` (completions mode) at the property ` +
+        `position to see what's actually defined.\n` +
+        `  • **Partial @param** — if this fires inside a partial / command / query, declare the ` +
+        `parameter in the file's \`{% doc %}\` block so the linter knows its shape.`,
+      fixes: [{
+        type: 'guidance',
+        description:
+          `Re-read the upstream message for the object and property names, then verify against ` +
+          `the relevant \`app/schema/
        .yml\`, the partial's \`{% doc %}\` block, or via ` +
+          `\`lookup\` (completions mode) at the property position.`,
+      }],
+      confidence: 0.4,
+    }),
+  },
 ];
diff --git a/src/dashboard.js b/src/dashboard.js
index d509463..7cbc33e 100644
--- a/src/dashboard.js
+++ b/src/dashboard.js
@@ -160,6 +160,7 @@ export function buildDashboardHtml() {
   .badge.error { color: var(--red); }
   .badge.info { color: var(--blue); }
   .badge.warn { color: var(--yellow); }
+  .badge.muted { color: var(--muted); }
   
   .duration { color: var(--muted); font-size: 12px; white-space: nowrap; }
   .ts { color: var(--muted); font-size: 11px; white-space: nowrap; }
@@ -1324,6 +1325,20 @@ export function buildDashboardHtml() {
     
+    
+      
+      
+      
+      
+      
+      
+    
        
@@ -2199,15 +2214,20 @@ async function exportSession() {
   const now = new Date().toISOString();
   const a = analysisData;
 
-  var [analyticsStats, scorecards, ruleScoresData, funnelData, gapsData, engineMap, recommendations, sessionsData] = await Promise.all([
+  // Honour the same Stats-since dropdown the live analytics tab uses, so the
+  // exported Markdown matches what the operator just saw on screen.
+  var sinceQ = resolveSinceQuerySegment();
+  var sinceLead = sinceLeadingQuery();
+  var [analyticsStats, scorecards, ruleScoresData, funnelData, gapsData, engineMap, recommendations, sessionsData, baselineMeta] = await Promise.all([
     fetch(BASE + '/api/analytics/stats').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/scorecards?min_cohort=1').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/rule-performance').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/funnel').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/knowledge-gaps').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/scorecards?min_cohort=1' + sinceQ).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/rule-performance' + sinceLead).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/funnel' + sinceLead).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/knowledge-gaps' + sinceLead).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
     fetch(BASE + '/api/engine-map').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/recommendations').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
-    fetch(BASE + '/api/analytics/sessions').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/recommendations' + sinceLead).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/sessions' + sinceLead).then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
+    fetch(BASE + '/api/analytics/baseline').then(function(r) { return r.ok ? r.json() : null; }).catch(function() { return null; }),
   ]);
 
   // Fetch drilldowns for problem checks (effectiveness < 50%)
@@ -2218,7 +2238,7 @@ async function exportSession() {
     return eff < 0.5 || c.emitted >= 5;
   });
   var drilldownPromises = problemChecks.map(function(c) {
-    return fetch(BASE + '/api/analytics/rule-drilldown?rule_id=' + encodeURIComponent(c.check) + '&limit=10')
+    return fetch(BASE + '/api/analytics/rule-drilldown?rule_id=' + encodeURIComponent(c.check) + '&limit=10' + sinceQ)
       .then(function(r) { return r.ok ? r.json() : null; })
       .then(function(data) { if (data) drilldowns[c.check] = data; })
       .catch(function() {});
@@ -2231,7 +2251,15 @@ async function exportSession() {
   L.push('');
   L.push('> Paste this to Claude and ask: "Analyze this report. What should I fix first? Which rules need rewriting? How healthy is the knowledge system?"');
   L.push('');
-  L.push('Generated: ' + now + ' | Project: ' + (d.projectDir || 'unknown') + ' | Version: ' + (d.version || 'unknown') + ' | Uptime: ' + fmtDuration(d.uptimeMs || 0));
+  // The "Stats since" disclosure makes the report self-documenting: an
+  // operator re-reading an old export shouldn't have to remember whether
+  // the dashboard was set to a baseline at the time. Echo whatever the
+  // server resolved (operator override → meta baseline → null).
+  var resolvedSince = scorecards?.since ?? null;
+  var statsSinceLabel = resolvedSince
+    ? resolvedSince
+    : (baselineMeta?.baseline_ts || 'full history');
+  L.push('Generated: ' + now + ' | Project: ' + (d.projectDir || 'unknown') + ' | Version: ' + (d.version || 'unknown') + ' | Uptime: ' + fmtDuration(d.uptimeMs || 0) + ' | Stats since: ' + statsSinceLabel);
   L.push('');
 
   // ── Executive Summary ──
@@ -2256,7 +2284,11 @@ async function exportSession() {
     var regRate = funnelData.regressed ? ((funnelData.regressed / funnelData.emitted) * 100).toFixed(0) : '0';
     findings.push('Overall funnel: ' + funnelData.emitted + ' diagnostics emitted -> ' + (funnelData.resolved || 0) + ' resolved (' + resRate + '%), ' + (funnelData.regressed || 0) + ' regressed (' + regRate + '%). Fix proposal rate: ' + (funnelData.fix_proposed || 0) + '/' + funnelData.emitted + '.');
   }
-  var harmful = cards.filter(function(c) { return rateVal(c.resolution_rate) - rateVal(c.mislead_rate) < 0; });
+  // Honour the sample-size gate: only call something HARMFUL when the
+  // server-side label says so. The server attaches a .label field per scorecard
+  // (see analytics-labels.js) — a row with a single regression no longer
+  // headlines as harmful, it lands in INSUFFICIENT_DATA.
+  var harmful = cards.filter(function(c) { return c.label === 'HARMFUL'; });
   if (harmful.length > 0) {
     findings.push('HARMFUL checks (regression > resolution): ' + harmful.map(function(c) { return c.check + ' (' + c.emitted + ' emitted, ' + ratePct(c.mislead_rate) + '% regression)'; }).join('; ') + '.');
   }
@@ -2400,8 +2432,13 @@ async function exportSession() {
     L.push('|---|---:|---:|---|---|---|---|');
     for (var cdi = 0; cdi < cards.length; cdi++) {
       var c = cards[cdi];
-      var eff = rateVal(c.resolution_rate) - rateVal(c.mislead_rate);
-      var effLabel = eff > 0.5 ? 'GOOD' : eff > 0.15 ? 'OK' : eff >= 0 ? 'LOW' : 'HARMFUL';
+      // Server-attached label honours the sample-size gate (INSUFFICIENT_DATA
+      // for N<5). Falling back to the inline calc keeps old DBs / pre-Phase-2
+      // responses readable, but the server is the source of truth.
+      var effLabel = c.label || (function () {
+        var eff = rateVal(c.resolution_rate) - rateVal(c.mislead_rate);
+        return eff > 0.5 ? 'GOOD' : eff > 0.15 ? 'OK' : eff >= 0 ? 'LOW' : 'HARMFUL';
+      })();
       L.push('| ' + c.check + ' | ' + c.emitted + ' | ' + (c.sample_size || 0) + ' | ' + rateCi(c.resolution_rate) + ' | ' + rateCi(c.mislead_rate) + ' | ' + rateCi(c.adoption_rate) + ' | ' + effLabel + ' |');
     }
     L.push('');
@@ -2457,7 +2494,12 @@ async function exportSession() {
     var sortedRules = [...rules].sort(function(x, y) { return (x.effectiveness || 0) - (y.effectiveness || 0); });
     for (var ri = 0; ri < sortedRules.length; ri++) {
       var r = sortedRules[ri];
-      var rStatus = r.unmatched ? 'UNMATCHED' : (r.effectiveness || 0) < 0.15 ? 'AT RISK' : 'OK';
+      // Server-attached label includes INSUFFICIENT_DATA when total_outcomes < 5.
+      // Inline fallback preserves legacy behaviour for un-labelled responses.
+      var rStatus = r.label || (
+        r.unmatched ? 'UNMATCHED' :
+        (r.effectiveness || 0) < 0.15 ? 'AT RISK' : 'OK'
+      );
       L.push('| ' + r.rule_id + ' | ' + r.emitted + ' | ' + ((r.resolution_rate || 0) * 100).toFixed(0) + '% | ' + ((r.regression_rate || 0) * 100).toFixed(0) + '% | ' + ((r.effectiveness || 0) * 100).toFixed(0) + '% | ' + rStatus + ' |');
     }
     L.push('');
@@ -4131,19 +4173,61 @@ let currentJourneyData = null;
 let selectedJourneyIdx = -1;
 let currentDrilldownData = null;
 
+/**
+ * Resolve the analytics-tab "Stats since" dropdown to the value the
+ * since= query param accepts:
+ *   - 'default' → empty (server reads meta baseline; widgets see the
+ *                 operator-set view by default — same UX as the report).
+ *   - 'all'     → 'all' (engine bypass / "All time").
+ *   - '24h'     → ISO of (now - 24h).
+ *   - '7d'      → ISO of (now - 7d).
+ *   - 'custom'  → ISO entered into the custom input.
+ *
+ * Returned value is appended as &since= (or omitted when default).
+ *
+ * NOTE: this lives inside the giant template literal that builds the
+ * dashboard HTML — so JSDoc cannot use backticks for code emphasis. See
+ * the corresponding feedback memory for context.
+ */
+function resolveSinceQuerySegment() {
+  const sel = document.getElementById('an-since-select');
+  const choice = sel?.value || 'default';
+  if (choice === 'default') return '';
+  if (choice === 'all')     return '&since=all';
+  if (choice === '24h')     return '&since=' + encodeURIComponent(new Date(Date.now() - 86_400_000).toISOString());
+  if (choice === '7d')      return '&since=' + encodeURIComponent(new Date(Date.now() - 7 * 86_400_000).toISOString());
+  if (choice === 'custom') {
+    const v = (document.getElementById('an-since-custom')?.value || '').trim();
+    if (!v) return '';
+    return '&since=' + encodeURIComponent(v);
+  }
+  return '';
+}
+
+/** As above, but for an endpoint that has no other query string yet. */
+function sinceLeadingQuery() {
+  const seg = resolveSinceQuerySegment();
+  return seg ? '?' + seg.slice(1) : '';
+}
+
 async function fetchAnalytics() {
   const tsEl = document.getElementById('an-last-fetched');
   tsEl.textContent = 'refreshing...';
 
+  // Composed once per refresh — every endpoint sees the same filter state.
+  const sinceQ = resolveSinceQuerySegment();
+  const sinceLead = sinceLeadingQuery();
+
   try {
-    const [statsR, scorecardsR, sessionsR, recsR, bigramsR, ruleScoresR, suggestedR] = await Promise.all([
+    const [statsR, scorecardsR, sessionsR, recsR, bigramsR, ruleScoresR, suggestedR, baselineR] = await Promise.all([
       fetch(BASE + '/api/analytics/stats').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/scorecards?min_cohort=1').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/sessions').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/recommendations').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/bigrams').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/rule-performance?min_emitted=1').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/suggested-rules').then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/scorecards?min_cohort=1' + sinceQ).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/sessions' + sinceLead).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/recommendations' + sinceLead).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/bigrams' + sinceLead).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/rule-performance?min_emitted=1' + sinceQ).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/suggested-rules' + sinceLead).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/baseline').then(r => r.ok ? r.json() : null).catch(() => null),
     ]);
 
     analyticsData = {
@@ -4154,6 +4238,10 @@ async function fetchAnalytics() {
       bigrams: bigramsR?.bigrams || [],
       ruleScores: ruleScoresR?.scores || [],
       suggestedRules: suggestedR?.suggestions || [],
+      // Echo from the server's resolved filter — used by renderers and the
+      // "Stats since" status pill.
+      since: scorecardsR?.since ?? null,
+      baseline: baselineR ?? { baseline_ts: null, set_at: null },
     };
 
     renderAnalyticsStats();
@@ -4163,6 +4251,7 @@ async function fetchAnalytics() {
     renderAnalyticsBigrams();
     renderRuleScores();
     renderSuggestedRules();
+    renderBaselineStatePill();
     fetchPromotedRules();
     fetchCalibrationChart();
     fetchFunnelChart();
@@ -4175,6 +4264,53 @@ async function fetchAnalytics() {
   }
 }
 
+/**
+ * Update the small inline pill next to the baseline buttons so the operator
+ * sees, at a glance, what filter state the analytics tab is rendering.
+ */
+function renderBaselineStatePill() {
+  const el = document.getElementById('an-baseline-state');
+  if (!el) return;
+  const baseline = analyticsData?.baseline?.baseline_ts;
+  const since = analyticsData?.since;
+  if (since && since !== baseline) {
+    // Operator picked a non-default since (24h / 7d / custom / all).
+    el.textContent = 'Filter: ' + since.slice(0, 16);
+  } else if (baseline) {
+    el.textContent = 'Baseline: ' + baseline.slice(0, 16);
+  } else {
+    el.textContent = 'No baseline set';
+  }
+}
+
+/**
+ * POST /api/analytics/baseline with a timestamp or null. After mutation,
+ * refresh the entire analytics view so every widget reflects the change.
+ */
+async function setAnalyticsBaseline(ts) {
+  try {
+    const res = await fetch(BASE + '/api/analytics/baseline', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ baseline_ts: ts }),
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      alert('Baseline update failed: ' + (body.error || res.status));
+      return;
+    }
+    // Snap back to "Since baseline (default)" so the operator sees the
+    // newly-set baseline take effect immediately, not the prior since
+    // selection (which would shadow it).
+    const sel = document.getElementById('an-since-select');
+    if (sel) sel.value = 'default';
+    document.getElementById('an-since-custom').style.display = 'none';
+    await fetchAnalytics();
+  } catch (e) {
+    alert('Baseline update failed: ' + e.message);
+  }
+}
+
 async function rebuildAnalytics() {
   const btn = document.getElementById('an-rebuild-btn');
   btn.disabled = true;
@@ -4369,11 +4505,18 @@ function renderRuleScores() {
         + '
        '
         + ''
         + ''
-        + ''
+        + ''
         + '';
     }).join('')
     + '
        
     
     
   
 
   
        ' + s.regressed + '' + s.adopted + '' + effPct + '%' + (s.unmatched
-          ? 'UNMATCHED'
-          : s.effectiveness < 0.15
-            ? 'AT RISK'
-            : 'ACTIVE') + '' + (function () {
+            // Server-attached label is the source of truth (analytics-labels.js).
+            // Inline fallback preserves the badge UX for un-labelled rows.
+            const lbl = s.label || (
+              s.unmatched ? 'UNMATCHED' :
+              (s.effectiveness ?? 0) < 0.15 ? 'AT RISK' : 'OK'
+            );
+            if (lbl === 'UNMATCHED')         return 'UNMATCHED';
+            if (lbl === 'INSUFFICIENT_DATA') return 'INSUFFICIENT DATA';
+            if (lbl === 'AT RISK')           return 'AT RISK';
+            return 'ACTIVE';
+          })() + '
        ';
@@ -4400,7 +4543,7 @@ async function showRuleDrilldown(ruleId, check) {
   try {
     const baseCheck = check.includes('.') ? check.split('.')[0] : check;
     const [drillRes, hintRes] = await Promise.all([
-      fetch(BASE + '/api/analytics/rule-drilldown?rule_id=' + encodeURIComponent(ruleId)),
+      fetch(BASE + '/api/analytics/rule-drilldown?rule_id=' + encodeURIComponent(ruleId) + resolveSinceQuerySegment()),
       fetch(BASE + '/api/hints?name=' + encodeURIComponent(baseCheck)),
     ]);
     const drill = drillRes.ok ? await drillRes.json() : null;
@@ -4998,7 +5141,7 @@ async function loadDiagnosticJourney(templateFp, check) {
     const qs = templateFp
       ? 'template_fp=' + encodeURIComponent(templateFp)
       : 'check=' + encodeURIComponent(check);
-    const r = await fetch(BASE + '/api/analytics/journey?' + qs);
+    const r = await fetch(BASE + '/api/analytics/journey?' + qs + resolveSinceQuerySegment());
     if (!r.ok) throw new Error('HTTP ' + r.status);
     const journey = await r.json();
     renderJourneyTimeline(el, journey);
@@ -5194,7 +5337,7 @@ async function fetchCalibrationChart() {
   if (!el) return;
 
   try {
-    const r = await fetch(BASE + '/api/analytics/calibration?buckets=10');
+    const r = await fetch(BASE + '/api/analytics/calibration?buckets=10' + resolveSinceQuerySegment());
     if (!r.ok) throw new Error('HTTP ' + r.status);
     const d = await r.json();
     const cal = d.calibration || d;
@@ -5263,7 +5406,7 @@ async function fetchFunnelChart() {
   if (!el) return;
 
   try {
-    const r = await fetch(BASE + '/api/analytics/funnel');
+    const r = await fetch(BASE + '/api/analytics/funnel' + sinceLeadingQuery());
     if (!r.ok) throw new Error('HTTP ' + r.status);
     const d = await r.json();
     renderFunnelChart(el, d);
@@ -5315,7 +5458,7 @@ async function fetchHeatmap() {
   if (!el) return;
 
   try {
-    const r = await fetch(BASE + '/api/analytics/rule-heatmap');
+    const r = await fetch(BASE + '/api/analytics/rule-heatmap' + sinceLeadingQuery());
     if (!r.ok) throw new Error('HTTP ' + r.status);
     const d = await r.json();
     renderHeatmap(el, d.cells || []);
@@ -5374,8 +5517,8 @@ async function fetchRadarChart() {
 
   try {
     const [gapsR, funnelR] = await Promise.all([
-      fetch(BASE + '/api/analytics/knowledge-gaps').then(r => r.ok ? r.json() : null).catch(() => null),
-      fetch(BASE + '/api/analytics/funnel').then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/knowledge-gaps' + sinceLeadingQuery()).then(r => r.ok ? r.json() : null).catch(() => null),
+      fetch(BASE + '/api/analytics/funnel' + sinceLeadingQuery()).then(r => r.ok ? r.json() : null).catch(() => null),
     ]);
 
     const gaps = gapsR?.gaps || [];
@@ -6168,6 +6311,30 @@ document.addEventListener('DOMContentLoaded', () => {
   document.getElementById('an-refresh-btn').addEventListener('click', fetchAnalytics);
   document.getElementById('an-rebuild-btn').addEventListener('click', rebuildAnalytics);
 
+  // Reporting baseline + since-filter controls.
+  const sinceSelect = document.getElementById('an-since-select');
+  const sinceCustom = document.getElementById('an-since-custom');
+  if (sinceSelect) {
+    sinceSelect.addEventListener('change', () => {
+      sinceCustom.style.display = sinceSelect.value === 'custom' ? '' : 'none';
+      // For non-custom selections, refetch immediately. Custom waits for the
+      // operator to hit Enter or blur the text input.
+      if (sinceSelect.value !== 'custom') fetchAnalytics();
+    });
+  }
+  if (sinceCustom) {
+    sinceCustom.addEventListener('change', fetchAnalytics);
+    sinceCustom.addEventListener('keydown', (e) => { if (e.key === 'Enter') fetchAnalytics(); });
+  }
+  const baselineSetBtn = document.getElementById('an-baseline-set-btn');
+  if (baselineSetBtn) {
+    baselineSetBtn.addEventListener('click', () => setAnalyticsBaseline(new Date().toISOString()));
+  }
+  const baselineClearBtn = document.getElementById('an-baseline-clear-btn');
+  if (baselineClearBtn) {
+    baselineClearBtn.addEventListener('click', () => setAnalyticsBaseline(null));
+  }
+
   // False Positive Manager
   document.getElementById('fp-add-btn').addEventListener('click', addSuppression);
 
@@ -6641,9 +6808,12 @@ async function fetchAdaptiveImpact() {
   try {
     // Parallel: impact summary (live engine state) + rule-performance list
     // (every rule_id ever seen — powers the autocomplete datalist).
+    // Engine-impact is windowed (24h) — leaves baseline alone. The
+    // datalist-populating rule-performance call honours the operator's
+    // baseline so autocomplete reflects what the analytics tab is showing.
     const [impactR, perfR] = await Promise.all([
       fetch(BASE + '/api/engine/impact'),
-      fetch(BASE + '/api/analytics/rule-performance?min_emitted=1'),
+      fetch(BASE + '/api/analytics/rule-performance?min_emitted=1' + resolveSinceQuerySegment()),
     ]);
     if (!impactR.ok) throw new Error('HTTP ' + impactR.status);
     adaptiveImpactCache = await impactR.json();
diff --git a/src/http-server.js b/src/http-server.js
index 0ae5dcd..7ec4a8e 100644
--- a/src/http-server.js
+++ b/src/http-server.js
@@ -12,6 +12,7 @@ import { getProjectMap } from './tools/project-map.js';
 import { buildDependencyGraph } from './core/dependency-graph.js';
 import { checkScorecards, sessionSummaries, recommendations, toolSequenceBigrams, diagnosticJourney, confidenceCalibration, fixAdoptionFunnel, knowledgeGaps, ruleScoresByCategory, ruleDrilldown, rulePerformance, adaptiveModeImpact, fixRulePerformance } from './core/analytics-queries.js';
 import { ruleScores, suggestedRules, retrieveCasesByCheck, generateRuleTemplate, synthesizeGuardPredicate } from './core/case-base.js';
+import { withCheckLabels, withRuleLabels } from './core/analytics-labels.js';
 import { addPromotedRule, removePromotedRule, listPromotedRules } from './core/rules/promoted-rules.js';
 import { reloadRules, loadAllRules } from './core/rules/index.js';
 import { runRules, getDisabledRules, getAllChecksWithRules, getRulesForCheck, getDisabledRuleDetails, getForceEnabledRules, getForceDisabledRules } from './core/rules/engine.js';
@@ -144,6 +145,10 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
         return handleCall(registry, body, res);
       }
 
+      if (url.pathname === '/api/analytics/baseline') {
+        return handleAnalyticsBaselineSet(analyticsStore, body, res);
+      }
+
       if (url.pathname === '/api/pos-cli/data-clean') {
         return handlePosCliCommand(posCliPath, projectDir, body, 'data-clean', log, res);
       }
@@ -187,12 +192,16 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
       return sendJson(res, 200, analyticsStore.stats());
     }
 
+    if (method === 'GET' && url.pathname === '/api/analytics/baseline') {
+      return handleAnalyticsBaselineGet(analyticsStore, res);
+    }
+
     if (method === 'GET' && url.pathname === '/api/analytics/scorecards') {
       return handleAnalyticsScorecards(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/sessions') {
-      return handleAnalyticsSessions(analyticsStore, res);
+      return handleAnalyticsSessions(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/recommendations') {
@@ -220,7 +229,7 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/suggested-rules') {
-      return handleSuggestedRules(analyticsStore, res);
+      return handleSuggestedRules(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/cases') {
@@ -240,15 +249,15 @@ export function startHttp(registry, { port, log, version, logPath, getStatus, re
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/funnel') {
-      return handleFixAdoptionFunnel(analyticsStore, res);
+      return handleFixAdoptionFunnel(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/knowledge-gaps') {
-      return handleKnowledgeGaps(analyticsStore, res);
+      return handleKnowledgeGaps(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/analytics/rule-heatmap') {
-      return handleRuleHeatmap(analyticsStore, res);
+      return handleRuleHeatmap(analyticsStore, url, res);
     }
 
     if (method === 'GET' && url.pathname === '/api/rules/checks') {
@@ -790,62 +799,70 @@ function handleDeletePromotedRule(projectDir, url, res) {
 
 function handleDiagnosticJourney(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
-  let templateFp = url.searchParams.get('template_fp');
-  const check = url.searchParams.get('check');
-  if (!templateFp && check) {
-    const row = analyticsStore.queryOne(
-      `SELECT template_fp, COUNT(*) as cnt FROM diagnostics WHERE check_name = ? AND template_fp IS NOT NULL GROUP BY template_fp ORDER BY cnt DESC LIMIT 1`,
-      [check],
-    );
-    templateFp = row?.template_fp;
-  }
-  if (!templateFp) return sendJson(res, 400, { error: 'template_fp or check parameter required' });
   try {
-    const journey = diagnosticJourney(analyticsStore, templateFp);
-    sendJson(res, 200, journey);
+    const since = parseSinceParam(url);
+    let templateFp = url.searchParams.get('template_fp');
+    const check = url.searchParams.get('check');
+    if (!templateFp && check) {
+      const row = analyticsStore.queryOne(
+        `SELECT template_fp, COUNT(*) as cnt FROM diagnostics WHERE check_name = ? AND template_fp IS NOT NULL GROUP BY template_fp ORDER BY cnt DESC LIMIT 1`,
+        [check],
+      );
+      templateFp = row?.template_fp;
+    }
+    if (!templateFp) return sendJson(res, 400, { error: 'template_fp or check parameter required' });
+    const journey = diagnosticJourney(analyticsStore, templateFp, { since });
+    sendJson(res, 200, { ...journey, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleConfidenceCalibration(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const buckets = parseInt(url.searchParams.get('buckets') || '10', 10);
-    const calibration = confidenceCalibration(analyticsStore, { buckets: Math.min(Math.max(buckets, 2), 20) });
-    sendJson(res, 200, { calibration });
+    const calibration = confidenceCalibration(analyticsStore, {
+      buckets: Math.min(Math.max(buckets, 2), 20),
+      since,
+    });
+    sendJson(res, 200, { calibration, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
-function handleFixAdoptionFunnel(analyticsStore, res) {
+function handleFixAdoptionFunnel(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
-    const funnel = fixAdoptionFunnel(analyticsStore);
-    sendJson(res, 200, funnel);
+    const since = parseSinceParam(url);
+    const funnel = fixAdoptionFunnel(analyticsStore, { since });
+    sendJson(res, 200, { ...funnel, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
-function handleKnowledgeGaps(analyticsStore, res) {
+function handleKnowledgeGaps(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
-    const gaps = knowledgeGaps(analyticsStore);
-    sendJson(res, 200, { gaps });
+    const since = parseSinceParam(url);
+    const gaps = knowledgeGaps(analyticsStore, { since });
+    sendJson(res, 200, { gaps, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
-function handleRuleHeatmap(analyticsStore, res) {
+function handleRuleHeatmap(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
-    const cells = ruleScoresByCategory(analyticsStore);
-    sendJson(res, 200, { cells });
+    const since = parseSinceParam(url);
+    const cells = ruleScoresByCategory(analyticsStore, { since });
+    sendJson(res, 200, { cells, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
@@ -1344,6 +1361,63 @@ function readLogTail(logPath, limit) {
 
 // ── Analytics handlers (Phase B) ───────────────────────────────────────────
 
+/**
+ * Parse the `since` query parameter into the value the analytics-queries +
+ * case-base reporting paths accept:
+ *
+ *   - `?since=all`            → null  (explicit bypass — operator clicked
+ *                                       "All time" in the dashboard)
+ *   - `?since=ISO`            → string (explicit override)
+ *   - `?since` absent / empty → undefined (function looks up meta baseline)
+ *
+ * Validates the ISO string by attempting Date parse; rejects with a thrown
+ * Error so the surrounding try/catch returns 400. Strict validation is the
+ * point — silently accepting garbage means an operator typing a bad date
+ * sees stats they don't expect with no error.
+ *
+ * Exported so unit tests can pin the parsing contract without spinning up
+ * the HTTP server. (Server startup uses bun:sqlite via analytics-store,
+ * which fails under integration tests that spawn `node bin/...`.)
+ */
+export function parseSinceParam(url) {
+  const raw = url.searchParams.get('since');
+  if (raw == null || raw === '') return undefined;
+  if (raw === 'all') return null;
+  const parsed = new Date(raw);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`since must be 'all' or a valid ISO timestamp; got '${raw}'`);
+  }
+  return raw;
+}
+
+function handleAnalyticsBaselineGet(analyticsStore, res) {
+  if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
+  try {
+    sendJson(res, 200, analyticsStore.getBaselineMeta());
+  } catch (e) {
+    sendJson(res, 500, { error: e.message });
+  }
+}
+
+function handleAnalyticsBaselineSet(analyticsStore, body, res) {
+  if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
+  try {
+    // Body shape: { baseline_ts: ISO } to set, { baseline_ts: null } to clear.
+    if (!body || typeof body !== 'object') {
+      return sendJson(res, 400, { error: 'request body must be an object' });
+    }
+    if (!('baseline_ts' in body)) {
+      return sendJson(res, 400, { error: 'missing required field: baseline_ts (ISO string or null)' });
+    }
+    analyticsStore.setBaselineTs(body.baseline_ts);
+    sendJson(res, 200, { ok: true, ...analyticsStore.getBaselineMeta() });
+  } catch (e) {
+    // setBaselineTs throws TypeError on invalid input — surface as 400.
+    const status = e instanceof TypeError ? 400 : 500;
+    sendJson(res, status, { error: e.message });
+  }
+}
+
 function handleAnalyticsRebuild(analyticsStore, sessionsDir, onAnalyticsRebuild, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   if (!sessionsDir) return sendJson(res, 400, { error: 'sessions dir not configured' });
@@ -1359,122 +1433,160 @@ function handleAnalyticsRebuild(analyticsStore, sessionsDir, onAnalyticsRebuild,
 function handleAnalyticsScorecards(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const sessionId = url.searchParams.get('session_id') || undefined;
     const minCohort = parseInt(url.searchParams.get('min_cohort') || '10', 10);
-    const cards = checkScorecards(analyticsStore, { sessionId, minCohort });
-    sendJson(res, 200, { scorecards: cards });
+    const cards = checkScorecards(analyticsStore, { sessionId, minCohort, since });
+    sendJson(res, 200, { scorecards: withCheckLabels(cards), since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
-function handleAnalyticsSessions(analyticsStore, res) {
+function handleAnalyticsSessions(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
-    const summaries = sessionSummaries(analyticsStore);
-    sendJson(res, 200, { sessions: summaries });
+    const since = parseSinceParam(url);
+    const summaries = sessionSummaries(analyticsStore, { since });
+    sendJson(res, 200, { sessions: summaries, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleAnalyticsRecommendations(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const threshold = parseFloat(url.searchParams.get('threshold') || '0.3');
-    const recs = recommendations(analyticsStore, threshold);
-    sendJson(res, 200, { recommendations: recs });
+    const recs = recommendations(analyticsStore, threshold, { since });
+    sendJson(res, 200, { recommendations: recs, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleAnalyticsBigrams(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const sessionId = url.searchParams.get('session_id') || undefined;
-    const bigrams = toolSequenceBigrams(analyticsStore, { sessionId });
-    sendJson(res, 200, { bigrams });
+    const bigrams = toolSequenceBigrams(analyticsStore, { sessionId, since });
+    sendJson(res, 200, { bigrams, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleRuleScores(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const minEmitted = parseInt(url.searchParams.get('min_emitted') || '5', 10);
-    const scores = ruleScores(analyticsStore, { minEmitted });
-    sendJson(res, 200, { scores });
+    const scores = ruleScores(analyticsStore, { minEmitted, since });
+    sendJson(res, 200, { scores: withRuleLabels(scores), since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleRulePerformance(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const minEmitted = parseInt(url.searchParams.get('min_emitted') || '1', 10);
-    const scores = rulePerformance(analyticsStore, { minEmitted });
-    sendJson(res, 200, { scores });
+    const scores = rulePerformance(analyticsStore, { minEmitted, since });
+    sendJson(res, 200, { scores: withRuleLabels(scores), since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleFixRulePerformance(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const minProposed = parseInt(url.searchParams.get('min_proposed') || '1', 10);
-    const scores = fixRulePerformance(analyticsStore, { minProposed });
-    sendJson(res, 200, { scores });
+    const scores = fixRulePerformance(analyticsStore, { minProposed, since });
+    sendJson(res, 200, { scores, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleRuleDrilldown(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const ruleId = url.searchParams.get('rule_id');
     if (!ruleId) return sendJson(res, 400, { error: 'rule_id parameter required' });
     const limit = Math.min(parseInt(url.searchParams.get('limit') || '30', 10), 100);
-    const data = ruleDrilldown(analyticsStore, ruleId, { limit });
-    sendJson(res, 200, data);
+    const data = ruleDrilldown(analyticsStore, ruleId, { limit, since });
+    sendJson(res, 200, { ...data, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
-function handleSuggestedRules(analyticsStore, res) {
+function handleSuggestedRules(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
-    const suggestions = suggestedRules(analyticsStore).map(s => {
-      const guards = synthesizeGuardPredicate(analyticsStore, s.check, s.template_fp);
+    const since = parseSinceParam(url);
+    const suggestions = suggestedRules(analyticsStore, new Set(), { since }).map(s => {
+      // Forward the same since to guard synthesis so the inferred guard
+      // window matches the suggestion window.
+      const guards = synthesizeGuardPredicate(analyticsStore, s.check, s.template_fp, { since });
       return {
         ...s,
         when: guards,
         template: generateRuleTemplate(s, guards),
       };
     });
-    sendJson(res, 200, { suggestions });
+    sendJson(res, 200, { suggestions, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
 function handleCases(analyticsStore, url, res) {
   if (!analyticsStore) return sendJson(res, 503, { error: 'analytics store not available' });
   try {
+    const since = parseSinceParam(url);
     const check = url.searchParams.get('check');
     if (!check) return sendJson(res, 400, { error: 'check parameter required' });
-    const cases = retrieveCasesByCheck(analyticsStore, check, { minCases: 1 });
-    sendJson(res, 200, { cases });
+    const cases = retrieveCasesByCheck(analyticsStore, check, { minCases: 1, since });
+    sendJson(res, 200, { cases, since: resolvedSinceForResponse(analyticsStore, since) });
   } catch (e) {
-    sendJson(res, 500, { error: e.message });
+    sendJson(res, sinceErrorStatus(e), { error: e.message });
   }
 }
 
+/**
+ * Surface what the queries actually filtered by. When `since` was undefined
+ * (meta default), this returns the meta value so the dashboard can show a
+ * "Stats since: " banner without a separate round-trip. When the
+ * caller explicitly passed `?since=all`, returns null. Tolerates errors so
+ * a missing baseline meta column never breaks the analytics response.
+ */
+function resolvedSinceForResponse(store, sinceArg) {
+  if (sinceArg === null) return null;
+  if (typeof sinceArg === 'string') return sinceArg;
+  try {
+    return store.getBaselineTs?.() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `parseSinceParam` throws on a malformed `since` query param; surface as
+ * 400 (client error). Anything else propagates the existing 500 path.
+ */
+function sinceErrorStatus(err) {
+  if (err && typeof err.message === 'string' && err.message.includes("since must be")) return 400;
+  return 500;
+}
+
 function readJsonBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
diff --git a/src/server.js b/src/server.js
index 687b7a8..2e5b421 100644
--- a/src/server.js
+++ b/src/server.js
@@ -147,7 +147,12 @@ export async function createServer({ projectDir, httpPort = 0 }) {
     }
     if (!analyticsStore) return;
     try {
-      const scores = ruleScores(analyticsStore, { minEmitted: 5 });
+      // Engine state: NEVER apply the operator's reporting baseline. Auto-disable
+      // requires full history so a freshly-set baseline can't accidentally
+      // narrow the sample below the disable threshold and re-enable harmful
+      // rules. `since: null` is the explicit bypass — see case-base.ruleScores
+      // JSDoc and the `resolveSince` contract.
+      const scores = ruleScores(analyticsStore, { minEmitted: 5, since: null });
       const disabled = scores.filter(s => s.disabled).map(s => s.rule_id);
       updateDisabledRules(disabled);
       setDisabledRuleDetails(scores.filter(s => s.disabled));
diff --git a/src/tools/server-status.js b/src/tools/server-status.js
index c29895e..5cb8e7b 100644
--- a/src/tools/server-status.js
+++ b/src/tools/server-status.js
@@ -13,7 +13,11 @@ export const serverStatusTool = {
       let disabledRules = [];
       if (ctx.analyticsStore) {
         try {
-          disabledRules = ruleScores(ctx.analyticsStore, { minEmitted: 10 })
+          // Engine state snapshot: bypass any operator reporting baseline.
+          // The disabled-rules list must reflect the case-base's full-history
+          // verdict — same data the runtime uses for syncDisabledRules.
+          // `since: null` is the explicit bypass; see case-base.ruleScores.
+          disabledRules = ruleScores(ctx.analyticsStore, { minEmitted: 10, since: null })
             .filter(s => s.disabled)
             .map(s => ({ rule_id: s.rule_id, effectiveness: s.effectiveness, total_outcomes: s.total_outcomes }));
         } catch { /* non-fatal */ }
diff --git a/tests/unit/analytics-labels.test.js b/tests/unit/analytics-labels.test.js
new file mode 100644
index 0000000..89de092
--- /dev/null
+++ b/tests/unit/analytics-labels.test.js
@@ -0,0 +1,234 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  LABEL_MIN_OUTCOMES,
+  checkLabel,
+  ruleLabel,
+  harmfulSummary,
+  withCheckLabels,
+  withRuleLabels,
+} from '../../src/core/analytics-labels.js';
+
+// ── checkLabel ──────────────────────────────────────────────────────────────
+
+describe('checkLabel: sample-size gate', () => {
+  test('INSUFFICIENT_DATA when sample_size < threshold (the GraphQLVariablesCheck case)', () => {
+    // The exact pattern from the 2026-04-30 report: 4 outcomes, all regressed.
+    // Pre-gate this would have read "HARMFUL"; post-gate we refuse to label.
+    const card = {
+      check: 'GraphQLVariablesCheck',
+      sample_size: 4,
+      resolution_rate: { mean: 0,    lower95: 0,    upper95: 0 },
+      mislead_rate:    { mean: 1,    lower95: 0.5,  upper95: 1 },
+    };
+    expect(checkLabel(card)).toBe('INSUFFICIENT_DATA');
+  });
+
+  test('INSUFFICIENT_DATA when sample_size === 0 (no outcomes at all)', () => {
+    expect(checkLabel({ sample_size: 0, resolution_rate: 0, mislead_rate: 0 })).toBe('INSUFFICIENT_DATA');
+  });
+
+  test('INSUFFICIENT_DATA at threshold-minus-one', () => {
+    expect(checkLabel({
+      sample_size: LABEL_MIN_OUTCOMES - 1,
+      resolution_rate: 1, mislead_rate: 0,
+    })).toBe('INSUFFICIENT_DATA');
+  });
+
+  test('crosses gate at LABEL_MIN_OUTCOMES — same effectiveness now labelled', () => {
+    expect(checkLabel({
+      sample_size: LABEL_MIN_OUTCOMES,
+      resolution_rate: 0.9, mislead_rate: 0.1,
+    })).toBe('GOOD');
+  });
+
+  test('falls back to total_outcomes when sample_size missing', () => {
+    expect(checkLabel({
+      total_outcomes: LABEL_MIN_OUTCOMES,
+      resolution_rate: 0.9, mislead_rate: 0.1,
+    })).toBe('GOOD');
+    expect(checkLabel({
+      total_outcomes: LABEL_MIN_OUTCOMES - 1,
+      resolution_rate: 0.9, mislead_rate: 0.1,
+    })).toBe('INSUFFICIENT_DATA');
+  });
+});
+
+describe('checkLabel: effectiveness buckets', () => {
+  // Once we're above the sample-size gate, the buckets must match the
+  // existing dashboard inline logic exactly so legacy reports don't shift.
+  const big = LABEL_MIN_OUTCOMES * 10;
+
+  test('GOOD when effectiveness > 0.5', () => {
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.9, mislead_rate: 0.1 })).toBe('GOOD');
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.7, mislead_rate: 0.0 })).toBe('GOOD');
+  });
+
+  test('OK when 0.15 < effectiveness ≤ 0.5', () => {
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.6, mislead_rate: 0.1 })).toBe('OK');
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.5, mislead_rate: 0.0 })).toBe('OK');
+  });
+
+  test('LOW when 0 ≤ effectiveness ≤ 0.15', () => {
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.2, mislead_rate: 0.1 })).toBe('LOW');
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.1, mislead_rate: 0.1 })).toBe('LOW');
+  });
+
+  test('HARMFUL when effectiveness < 0', () => {
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.1, mislead_rate: 0.5 })).toBe('HARMFUL');
+    expect(checkLabel({ sample_size: big, resolution_rate: 0.0, mislead_rate: 0.6 })).toBe('HARMFUL');
+  });
+});
+
+describe('checkLabel: input shape tolerance', () => {
+  test('accepts Beta-posterior {mean,...} objects (server-side payload shape)', () => {
+    const card = {
+      sample_size: 20,
+      resolution_rate: { mean: 0.85, lower95: 0.7, upper95: 0.95 },
+      mislead_rate:    { mean: 0.05, lower95: 0.0, upper95: 0.15 },
+    };
+    expect(checkLabel(card)).toBe('GOOD');
+  });
+
+  test('accepts bare numbers (legacy / test-shaped payloads)', () => {
+    expect(checkLabel({
+      sample_size: 20, resolution_rate: 0.85, mislead_rate: 0.05,
+    })).toBe('GOOD');
+  });
+
+  test('null/undefined card returns INSUFFICIENT_DATA without throwing', () => {
+    expect(checkLabel(null)).toBe('INSUFFICIENT_DATA');
+    expect(checkLabel(undefined)).toBe('INSUFFICIENT_DATA');
+    expect(checkLabel('not-an-object')).toBe('INSUFFICIENT_DATA');
+  });
+
+  test('NaN sample_size is treated as zero (not crashed)', () => {
+    expect(checkLabel({ sample_size: NaN, resolution_rate: 1, mislead_rate: 0 }))
+      .toBe('INSUFFICIENT_DATA');
+  });
+});
+
+// ── ruleLabel ───────────────────────────────────────────────────────────────
+
+describe('ruleLabel: precedence', () => {
+  test('UNMATCHED wins regardless of sample size', () => {
+    // Coverage gap is actionable on its own — one emit on a rule-less
+    // check still tells operators "write a rule for this". Sample-size
+    // gate must NOT mask it.
+    expect(ruleLabel({ unmatched: true, total_outcomes: 1, effectiveness: 0 }))
+      .toBe('UNMATCHED');
+    expect(ruleLabel({ unmatched: true, total_outcomes: 100, effectiveness: 0.9 }))
+      .toBe('UNMATCHED');
+  });
+
+  test('INSUFFICIENT_DATA when matched rule has < threshold outcomes', () => {
+    // The exact pattern from the 04-30 report: several AT-RISK rules with
+    // total_outcomes between 1 and 4. They become INSUFFICIENT_DATA.
+    expect(ruleLabel({ unmatched: false, total_outcomes: 4, effectiveness: -1 }))
+      .toBe('INSUFFICIENT_DATA');
+    expect(ruleLabel({ unmatched: false, total_outcomes: 1, effectiveness: 0 }))
+      .toBe('INSUFFICIENT_DATA');
+  });
+
+  test('AT RISK when effectiveness < 0.15 with enough samples', () => {
+    expect(ruleLabel({ unmatched: false, total_outcomes: 20, effectiveness: 0.1 }))
+      .toBe('AT RISK');
+    expect(ruleLabel({ unmatched: false, total_outcomes: 20, effectiveness: -0.5 }))
+      .toBe('AT RISK');
+  });
+
+  test('OK when effectiveness >= 0.15 with enough samples', () => {
+    expect(ruleLabel({ unmatched: false, total_outcomes: 20, effectiveness: 0.15 }))
+      .toBe('OK');
+    expect(ruleLabel({ unmatched: false, total_outcomes: 20, effectiveness: 0.9 }))
+      .toBe('OK');
+  });
+
+  test('null/undefined rule returns INSUFFICIENT_DATA without throwing', () => {
+    expect(ruleLabel(null)).toBe('INSUFFICIENT_DATA');
+    expect(ruleLabel(undefined)).toBe('INSUFFICIENT_DATA');
+  });
+
+  test('NaN effectiveness is INSUFFICIENT_DATA, not OK or AT RISK', () => {
+    expect(ruleLabel({ unmatched: false, total_outcomes: 20, effectiveness: NaN }))
+      .toBe('INSUFFICIENT_DATA');
+  });
+});
+
+// ── harmfulSummary ──────────────────────────────────────────────────────────
+
+describe('harmfulSummary', () => {
+  test('returns rows whose label is HARMFUL — never single-emit ghosts', () => {
+    const cards = [
+      // Ghost: 4 emits all regressed. Pre-gate flagged HARMFUL; post-gate filtered.
+      { check: 'OldGhost',     sample_size: 4,  resolution_rate: 0,    mislead_rate: 1 },
+      // Real: 30 outcomes, true regression-heavy.
+      { check: 'RealHarm',     sample_size: 30, resolution_rate: 0.1,  mislead_rate: 0.6 },
+      // Healthy: ignored.
+      { check: 'Healthy',      sample_size: 30, resolution_rate: 0.9,  mislead_rate: 0.05 },
+    ];
+    const harmful = harmfulSummary(cards);
+    expect(harmful).toHaveLength(1);
+    expect(harmful[0].check).toBe('RealHarm');
+  });
+
+  test('non-array input returns []', () => {
+    expect(harmfulSummary(null)).toEqual([]);
+    expect(harmfulSummary(undefined)).toEqual([]);
+    expect(harmfulSummary('nope')).toEqual([]);
+  });
+
+  test('empty array returns []', () => {
+    expect(harmfulSummary([])).toEqual([]);
+  });
+});
+
+// ── withCheckLabels / withRuleLabels ────────────────────────────────────────
+
+describe('withCheckLabels', () => {
+  test('attaches .label without mutating input rows', () => {
+    const cards = [
+      { check: 'A', sample_size: 30, resolution_rate: 0.9, mislead_rate: 0.05 },
+      { check: 'B', sample_size: 2,  resolution_rate: 0,   mislead_rate: 1 },
+    ];
+    const out = withCheckLabels(cards);
+    expect(out).toHaveLength(2);
+    expect(out[0].label).toBe('GOOD');
+    expect(out[1].label).toBe('INSUFFICIENT_DATA');
+    // input untouched — no .label leakage
+    expect('label' in cards[0]).toBe(false);
+    expect('label' in cards[1]).toBe(false);
+  });
+
+  test('non-array input returns []', () => {
+    expect(withCheckLabels(null)).toEqual([]);
+  });
+});
+
+describe('withRuleLabels', () => {
+  test('attaches .label without mutating input rows', () => {
+    const rules = [
+      { rule_id: 'X.foo', unmatched: true,  total_outcomes: 1,  effectiveness: 0 },
+      { rule_id: 'Y.bar', unmatched: false, total_outcomes: 30, effectiveness: 0.9 },
+      { rule_id: 'Z.baz', unmatched: false, total_outcomes: 2,  effectiveness: -1 },
+    ];
+    const out = withRuleLabels(rules);
+    expect(out[0].label).toBe('UNMATCHED');
+    expect(out[1].label).toBe('OK');
+    expect(out[2].label).toBe('INSUFFICIENT_DATA');
+    expect('label' in rules[0]).toBe(false);
+  });
+
+  test('non-array input returns []', () => {
+    expect(withRuleLabels(undefined)).toEqual([]);
+  });
+});
+
+// ── threshold export sanity ─────────────────────────────────────────────────
+
+describe('LABEL_MIN_OUTCOMES', () => {
+  test('exported as a positive integer ≥ 2', () => {
+    expect(typeof LABEL_MIN_OUTCOMES).toBe('number');
+    expect(Number.isInteger(LABEL_MIN_OUTCOMES)).toBe(true);
+    expect(LABEL_MIN_OUTCOMES).toBeGreaterThanOrEqual(2);
+  });
+});
diff --git a/tests/unit/analytics-queries.test.js b/tests/unit/analytics-queries.test.js
index 6ceb943..bb19e66 100644
--- a/tests/unit/analytics-queries.test.js
+++ b/tests/unit/analytics-queries.test.js
@@ -12,6 +12,9 @@ import {
   fixAdoptionFunnel,
   adaptiveModeImpact,
   fixRulePerformance,
+  ruleScoresByCategory,
+  knowledgeGaps,
+  confidenceCalibration,
 } from '../../src/core/analytics-queries.js';
 import { rmSync } from 'node:fs';
 import { join } from 'node:path';
@@ -512,3 +515,299 @@ describe('fixRulePerformance', () => {
     expect(out.map(r => r.rule_id)).toEqual(['heuristic:Common.text_edit']);
   });
 });
+
+// ── Reporting baseline (`since`) — tri-state contract ─────────────────────
+//
+// All reporting queries accept `opts.since`:
+//   - undefined ⇒ read store.getBaselineTs(); absent ⇒ no filter
+//   - null      ⇒ explicit bypass (engine-state callers)
+//   - ISO       ⇒ filter d.ts >= since (or pf.ts for fix-rule queries)
+//
+// Each test below seeds two timestamps — one before a midpoint, one after —
+// and asserts the query honours the explicit ISO, the absent meta default
+// (full history), and the meta-set value (auto-applied default).
+
+describe('reporting baseline: since param', () => {
+  const OLD = '2026-04-01T00:00:00.000Z';   // pre-midpoint
+  const NEW = '2026-04-30T00:00:00.000Z';   // post-midpoint
+  const MID = '2026-04-15T00:00:00.000Z';
+
+  function seedTwoEras() {
+    // Old + new emit on the same template — easy to count. Two emits in the
+    // OLD era share session 's1' so a single window can host both outcomes
+    // and the diagnostic↔outcome (fp, session_id, file) JOIN matches.
+    emitEvent(store, 's1', 'old1', 'CheckA', OLD);
+    emitEvent(store, 's1', 'old2', 'CheckA', OLD);
+    emitEvent(store, 's3', 'new1', 'CheckA', NEW);
+  }
+
+  function seedTwoErasWithOutcomes() {
+    seedTwoEras();
+    const wOld = store.insertWindow({
+      session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 0,
+      ts_start: OLD, ts_end: OLD,
+    });
+    const wNew = store.insertWindow({
+      session_id: 's3', file: 'app/views/pages/index.html.liquid', idx: 0,
+      ts_start: NEW, ts_end: NEW,
+    });
+    store.insertOutcome({ fp: 'old1', window_id: wOld, outcome: 'regressed' });
+    store.insertOutcome({ fp: 'old2', window_id: wOld, outcome: 'regressed' });
+    store.insertOutcome({ fp: 'new1', window_id: wNew, outcome: 'resolved' });
+  }
+
+  test('checkScorecards: ISO since filters out pre-baseline emits', () => {
+    seedTwoEras();
+    const all = checkScorecards(store, { minCohort: 1 });
+    expect(all[0].emitted).toBe(3);
+    const post = checkScorecards(store, { minCohort: 1, since: MID });
+    expect(post[0].emitted).toBe(1);
+  });
+
+  test('checkScorecards: outcome counts honour the same baseline', () => {
+    seedTwoErasWithOutcomes();
+    const post = checkScorecards(store, { minCohort: 1, since: MID });
+    // Only the post-baseline emit's outcome (resolved) should count.
+    expect(post[0].sample_size).toBe(1);
+    expect(post[0].resolution_rate.mean).toBeGreaterThan(0.5);
+  });
+
+  test('checkScorecards: since=null bypasses meta baseline', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    const all = checkScorecards(store, { minCohort: 1, since: null });
+    expect(all[0].emitted).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('checkScorecards: since=undefined reads meta baseline by default', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    const post = checkScorecards(store, { minCohort: 1 });
+    expect(post[0].emitted).toBe(1);
+    store.clearBaseline();
+  });
+
+  test('rulePerformance: ISO since filters by d.ts', () => {
+    seedTwoEras();
+    const all = rulePerformance(store);
+    expect(all[0].emitted).toBe(3);
+    const post = rulePerformance(store, { since: MID });
+    expect(post[0].emitted).toBe(1);
+  });
+
+  test('rulePerformance: outcome counts narrow to the window', () => {
+    seedTwoErasWithOutcomes();
+    const post = rulePerformance(store, { since: MID });
+    expect(post[0].total_outcomes).toBe(1);
+    expect(post[0].resolved).toBe(1);
+    expect(post[0].regressed).toBe(0);
+  });
+
+  test('rulePerformance: meta default fires when since is absent', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    expect(rulePerformance(store)[0].emitted).toBe(1);
+    store.clearBaseline();
+    expect(rulePerformance(store)[0].emitted).toBe(3);
+  });
+
+  test('fixAdoptionFunnel: emit + outcome counts narrow to the window', () => {
+    seedTwoErasWithOutcomes();
+    const post = fixAdoptionFunnel(store, { since: MID });
+    expect(post.emitted).toBe(1);
+    expect(post.resolved).toBe(1);
+    expect(post.regressed).toBe(0);
+    const all = fixAdoptionFunnel(store);
+    expect(all.emitted).toBe(3);
+    expect(all.regressed).toBe(2);
+  });
+
+  test('fixAdoptionFunnel: meta baseline + since=null bypass', () => {
+    seedTwoErasWithOutcomes();
+    store.setBaselineTs(MID);
+    expect(fixAdoptionFunnel(store).emitted).toBe(1);
+    expect(fixAdoptionFunnel(store, { since: null }).emitted).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('knowledgeGaps: filters total_emitted by since', () => {
+    // Need ≥3 emits to pass the HAVING gate post-filter.
+    emitEvent(store, 's1', 'old1', 'KGCheck', OLD);
+    emitEvent(store, 's1', 'old2', 'KGCheck', OLD);
+    emitEvent(store, 's1', 'new1', 'KGCheck', NEW);
+    emitEvent(store, 's1', 'new2', 'KGCheck', NEW);
+    emitEvent(store, 's1', 'new3', 'KGCheck', NEW);
+
+    const all = knowledgeGaps(store);
+    const allRow = all.find(r => r.check === 'KGCheck');
+    expect(allRow?.total_emitted).toBe(5);
+
+    const post = knowledgeGaps(store, { since: MID });
+    const postRow = post.find(r => r.check === 'KGCheck');
+    expect(postRow?.total_emitted).toBe(3);
+  });
+
+  test('confidenceCalibration: filters by d.ts', () => {
+    const wid = store.insertWindow({
+      session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 0,
+      ts_start: OLD, ts_end: NEW,
+    });
+    // Old: low confidence, regressed. New: high confidence, resolved.
+    store.ingestEvent({
+      v: 1, session_id: 's1', ts: OLD, kind: 'validator_emit',
+      fp: 'cal-old', file: 'app/views/pages/index.html.liquid',
+      hint_rule_id: 'X', confidence: 0.2, proposed_fixes: [],
+    });
+    store.ingestEvent({
+      v: 1, session_id: 's1', ts: NEW, kind: 'validator_emit',
+      fp: 'cal-new', file: 'app/views/pages/index.html.liquid',
+      hint_rule_id: 'X', confidence: 0.9, proposed_fixes: [],
+    });
+    store.insertOutcome({ fp: 'cal-old', window_id: wid, outcome: 'regressed' });
+    store.insertOutcome({ fp: 'cal-new', window_id: wid, outcome: 'resolved' });
+
+    const allBuckets = confidenceCalibration(store);
+    const allTotal = allBuckets.reduce((s, b) => s + b.sample_size, 0);
+    expect(allTotal).toBe(2);
+
+    const postBuckets = confidenceCalibration(store, { since: MID });
+    const postTotal = postBuckets.reduce((s, b) => s + b.sample_size, 0);
+    expect(postTotal).toBe(1);
+  });
+
+  test('ruleScoresByCategory: filters by d.ts', () => {
+    seedTwoErasWithOutcomes();
+    const all = ruleScoresByCategory(store);
+    const allRow = all.find(r => r.rule_id === 'CheckA');
+    expect(allRow.outcomes).toBe(3);
+    const post = ruleScoresByCategory(store, { since: MID });
+    const postRow = post.find(r => r.rule_id === 'CheckA');
+    expect(postRow.outcomes).toBe(1);
+  });
+
+  test('sessionSummaries: filters session list to those active in window', () => {
+    // Distinct sessions per era.
+    store.ingestEvent({ v: 1, session_id: 'old-only', ts: OLD, kind: 'server_start',
+      project_dir: '/tmp', version: '1.0', started_at: OLD });
+    toolCallEvent(store, 'old-only', 'validate_code', OLD);
+    toolCallEvent(store, 'new-only', 'validate_code', NEW);
+
+    const all = sessionSummaries(store);
+    expect(all.map(s => s.session_id).sort()).toEqual(['new-only', 'old-only']);
+
+    const post = sessionSummaries(store, { since: MID });
+    expect(post.map(s => s.session_id)).toEqual(['new-only']);
+  });
+
+  test('toolSequenceBigrams: filters events by ts', () => {
+    toolCallEvent(store, 's1', 'project_map', OLD);
+    toolCallEvent(store, 's1', 'scaffold',    OLD);
+    toolCallEvent(store, 's1', 'project_map', NEW);
+    toolCallEvent(store, 's1', 'validate_code', NEW);
+
+    const all = toolSequenceBigrams(store);
+    expect(all.find(b => b.bigram[0] === 'project_map' && b.bigram[1] === 'scaffold')).toBeDefined();
+
+    const post = toolSequenceBigrams(store, { since: MID });
+    expect(post.find(b => b.bigram[0] === 'project_map' && b.bigram[1] === 'scaffold')).toBeUndefined();
+    expect(post.find(b => b.bigram[0] === 'project_map' && b.bigram[1] === 'validate_code')).toBeDefined();
+  });
+
+  test('diagnosticJourney: filters timeline to post-baseline emits', () => {
+    store.ingestEvent({
+      v: 1, session_id: 's1', ts: OLD, kind: 'validator_emit',
+      fp: 'fp-old', template_fp: 'jt', file: 'app/views/pages/x.liquid',
+      hint_rule_id: 'CheckJ', proposed_fixes: [],
+    });
+    store.ingestEvent({
+      v: 1, session_id: 's2', ts: NEW, kind: 'validator_emit',
+      fp: 'fp-new', template_fp: 'jt', file: 'app/views/pages/x.liquid',
+      hint_rule_id: 'CheckJ', proposed_fixes: [],
+    });
+
+    const all = diagnosticJourney(store, 'jt');
+    expect(all.session_count).toBe(2);
+    const post = diagnosticJourney(store, 'jt', { since: MID });
+    expect(post.session_count).toBe(1);
+    expect(post.timeline[0].session_id).toBe('s2');
+  });
+
+  test('ruleDrilldown: filters samples + file/template stats', () => {
+    seedTwoErasWithOutcomes();
+    const all = ruleDrilldown(store, 'CheckA');
+    expect(all.samples).toHaveLength(3);
+    expect(all.file_distribution[0].emitted).toBe(3);
+
+    const post = ruleDrilldown(store, 'CheckA', { since: MID });
+    expect(post.samples).toHaveLength(1);
+    expect(post.file_distribution[0].emitted).toBe(1);
+    expect(post.file_distribution[0].resolved).toBe(1);
+    expect(post.file_distribution[0].regressed).toBe(0);
+  });
+
+  test('fixRulePerformance: filters by pf.ts', () => {
+    function emitWithFix(sid, fp, ts) {
+      store.ingestEvent({
+        v: 1, session_id: sid, ts, kind: 'validator_emit',
+        fp, template_fp: 'tpl', file: 'app/views/pages/x.liquid',
+        hint_rule_id: 'X.r',
+        proposed_fixes: [{ range: null, new_text_hash: 'h', kind: 'text_edit', rule_id: 'X.r' }],
+      });
+    }
+    emitWithFix('s1', 'oldA', OLD);
+    emitWithFix('s2', 'oldB', OLD);
+    emitWithFix('s3', 'new1', NEW);
+
+    const all = fixRulePerformance(store);
+    expect(all.find(r => r.rule_id === 'X.r').proposed).toBe(3);
+
+    const post = fixRulePerformance(store, { since: MID });
+    expect(post.find(r => r.rule_id === 'X.r').proposed).toBe(1);
+  });
+
+  test('recommendations: forwards since to checkScorecards', () => {
+    // Old era: clearly harmful. New era: clean.
+    for (let i = 0; i < 10; i++) {
+      emitEvent(store, 's1', `bad-${i}`, 'BadCheck', OLD);
+    }
+    const wOld = store.insertWindow({
+      session_id: 's1', file: 'app/views/pages/index.html.liquid', idx: 0,
+      ts_start: OLD, ts_end: OLD,
+    });
+    for (let i = 0; i < 10; i++) {
+      store.insertOutcome({ fp: `bad-${i}`, window_id: wOld, outcome: 'regressed' });
+    }
+
+    const allRecs = recommendations(store, 0.3);
+    expect(allRecs.find(r => r.check === 'BadCheck')).toBeDefined();
+    const postRecs = recommendations(store, 0.3, { since: MID });
+    expect(postRecs.find(r => r.check === 'BadCheck')).toBeUndefined();
+  });
+
+  test('resolveSince precedence: explicit ISO beats meta baseline', () => {
+    // meta says MID, query says OLD → query wins, sees everything.
+    store.setBaselineTs(MID);
+    seedTwoEras();
+    const out = checkScorecards(store, { minCohort: 1, since: OLD });
+    expect(out[0].emitted).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('store without getBaselineTs (mock) — undefined since means no filter', () => {
+    // Defensive: resolveSince must degrade gracefully when given a partial mock.
+    const fakeStore = {
+      query: store.query,
+      queryOne: store.queryOne,
+      // Note: no getBaselineTs.
+    };
+    seedTwoEras();
+    // Bind the real prepared-statement methods to the real db path so the
+    // fake store can still issue queries (we just test the resolver path).
+    fakeStore.query = (sql, params) => store.query(sql, params);
+    fakeStore.queryOne = (sql, params) => store.queryOne(sql, params);
+
+    const out = checkScorecards(fakeStore, { minCohort: 1 });
+    expect(out[0].emitted).toBe(3);
+  });
+});
diff --git a/tests/unit/analytics-store.test.js b/tests/unit/analytics-store.test.js
index 217c14d..345e3e8 100644
--- a/tests/unit/analytics-store.test.js
+++ b/tests/unit/analytics-store.test.js
@@ -90,6 +90,85 @@ describe('openAnalyticsStore', () => {
   });
 });
 
+describe('reporting baseline', () => {
+  test('absent by default — getBaselineTs returns null', () => {
+    expect(store.getBaselineTs()).toBeNull();
+    const meta = store.getBaselineMeta();
+    expect(meta.baseline_ts).toBeNull();
+    expect(meta.set_at).toBeNull();
+  });
+
+  test('setBaselineTs persists ISO + stamps set_at', () => {
+    const ts = '2026-04-30T12:00:00.000Z';
+    store.setBaselineTs(ts);
+    expect(store.getBaselineTs()).toBe(ts);
+    const meta = store.getBaselineMeta();
+    expect(meta.baseline_ts).toBe(ts);
+    // set_at is the wall-clock moment of the call — non-null + parseable.
+    expect(meta.set_at).not.toBeNull();
+    expect(Number.isFinite(new Date(meta.set_at).getTime())).toBe(true);
+  });
+
+  test('setBaselineTs(null) clears both keys', () => {
+    store.setBaselineTs('2026-04-30T12:00:00.000Z');
+    expect(store.getBaselineTs()).not.toBeNull();
+    store.setBaselineTs(null);
+    expect(store.getBaselineTs()).toBeNull();
+    expect(store.getBaselineMeta().set_at).toBeNull();
+  });
+
+  test('clearBaseline() removes both keys', () => {
+    store.setBaselineTs('2026-04-30T12:00:00.000Z');
+    store.clearBaseline();
+    expect(store.getBaselineTs()).toBeNull();
+    expect(store.getBaselineMeta().set_at).toBeNull();
+  });
+
+  test('overwrites a prior baseline (single source of truth)', () => {
+    store.setBaselineTs('2026-04-01T00:00:00.000Z');
+    store.setBaselineTs('2026-04-30T12:00:00.000Z');
+    expect(store.getBaselineTs()).toBe('2026-04-30T12:00:00.000Z');
+    // exactly one row each — no historical accumulation in the meta table
+    const rows = store.query(
+      `SELECT key FROM meta WHERE key IN ('analytics_baseline_ts','analytics_baseline_set_at')`,
+    );
+    expect(rows).toHaveLength(2);
+  });
+
+  test('rejects non-ISO inputs without mutating state', () => {
+    store.setBaselineTs('2026-04-30T12:00:00.000Z');
+    const before = store.getBaselineTs();
+    expect(() => store.setBaselineTs('not-a-date')).toThrow(TypeError);
+    expect(() => store.setBaselineTs(123)).toThrow(TypeError);
+    expect(() => store.setBaselineTs('')).toThrow(TypeError);
+    expect(store.getBaselineTs()).toBe(before);
+  });
+
+  test('survives store close/reopen — persisted in meta table', () => {
+    const ts = '2026-04-30T12:00:00.000Z';
+    store.setBaselineTs(ts);
+    store.close();
+    store = openAnalyticsStore(dbPath);
+    expect(store.getBaselineTs()).toBe(ts);
+  });
+
+  test('rebuild() preserves the baseline (rebuild clears derived data, not meta)', () => {
+    const sessionsRoot = tmpSessionDir();
+    const sess = join(sessionsRoot, 'session-1');
+    mkdirSync(sess, { recursive: true });
+    writeFileSync(join(sess, 'events.ndjson'), [
+      makeServerStartLine({ session_id: 's1' }),
+      makeValidatorEmitLine({ session_id: 's1', fp: 'a' }),
+    ].join('\n') + '\n');
+
+    store.setBaselineTs('2026-04-30T12:00:00.000Z');
+    store.rebuild(sessionsRoot);
+    expect(store.getBaselineTs()).toBe('2026-04-30T12:00:00.000Z');
+
+    rmSync(sessionsRoot, { recursive: true, force: true });
+  });
+});
+
 describe('ingestEvent', () => {
   test('inserts generic event', () => {
     store.ingestEvent({
diff --git a/tests/unit/case-base.test.js b/tests/unit/case-base.test.js
index 040c8fb..cfd8ed4 100644
--- a/tests/unit/case-base.test.js
+++ b/tests/unit/case-base.test.js
@@ -1,6 +1,6 @@
 import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
 import { openAnalyticsStore } from '../../src/core/analytics-store.js';
-import { retrieveCases, retrieveCasesByCheck, ruleScores, scoreRule, suggestedRules, generateRuleTemplate } from '../../src/core/case-base.js';
+import { retrieveCases, retrieveCasesByCheck, ruleScores, scoreRule, suggestedRules, generateRuleTemplate, synthesizeGuardPredicate } from '../../src/core/case-base.js';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -379,3 +379,174 @@ describe('Case base — F3: generateRuleTemplate', () => {
 });
 
 function RULE_DISABLE_THRESHOLD() { return 0.15; }
+
+// ── Reporting baseline (`since`) ─────────────────────────────────────────
+//
+// case-base reporting paths (retrieveCases*, ruleScores, suggestedRules,
+// synthesizeGuardPredicate) accept `opts.since`. Engine paths
+// (`scoreRule`, internal `resolveProbation`) MUST NOT — verified by
+// observing that scoreRule has no since parameter and engine call sites
+// in server.js / server-status.js pass `since: null` explicitly.
+
+describe('Case base — reporting baseline (`since`)', () => {
+  let store, dbPath;
+
+  const OLD = '2026-04-01T00:00:00.000Z';
+  const NEW = '2026-04-30T00:00:00.000Z';
+  const MID = '2026-04-15T00:00:00.000Z';
+
+  beforeEach(() => {
+    dbPath = tmpPath();
+    store = openAnalyticsStore(dbPath);
+  });
+  afterEach(() => { store.close(); });
+
+  function seedTwoEras() {
+    // Use seedStore's default session_id 'sess-1' / file 'test.liquid' for
+    // both diagnostics and the implicit window — case-base joins outcomes
+    // back to diagnostics on (fp, session_id, file) so they must match.
+    seedStore(store,
+      [
+        { fp: 'old1', template_fp: 'tpl1', check_name: 'UnknownFilter', hint_rule_id: 'UnknownFilter.typo', ts: OLD },
+        { fp: 'old2', template_fp: 'tpl1', check_name: 'UnknownFilter', hint_rule_id: 'UnknownFilter.typo', ts: OLD },
+        { fp: 'new1', template_fp: 'tpl1', check_name: 'UnknownFilter', hint_rule_id: 'UnknownFilter.typo', ts: NEW },
+      ],
+      {
+        windows: [{ id: 1 }],
+        outcomes: [
+          { fp: 'old1', outcome: 'regressed' },
+          { fp: 'old2', outcome: 'regressed' },
+          { fp: 'new1', outcome: 'resolved', fix_applied: 'verbatim' },
+        ],
+      }
+    );
+  }
+
+  test('retrieveCases: ISO since narrows the case set', () => {
+    seedTwoEras();
+    const all = retrieveCases(store, 'UnknownFilter', 'tpl1', { minCases: 1 });
+    expect(all.total).toBe(3);
+    const post = retrieveCases(store, 'UnknownFilter', 'tpl1', { minCases: 1, since: MID });
+    expect(post.total).toBe(1);
+  });
+
+  test('retrieveCases: meta baseline applies when since omitted', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    const post = retrieveCases(store, 'UnknownFilter', 'tpl1', { minCases: 1 });
+    expect(post.total).toBe(1);
+    store.clearBaseline();
+    const all = retrieveCases(store, 'UnknownFilter', 'tpl1', { minCases: 1 });
+    expect(all.total).toBe(3);
+  });
+
+  test('retrieveCases: since=null bypasses meta baseline', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    const all = retrieveCases(store, 'UnknownFilter', 'tpl1', { minCases: 1, since: null });
+    expect(all.total).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('retrieveCasesByCheck: forwards since through to retrieveCases', () => {
+    seedTwoEras();
+    const all = retrieveCasesByCheck(store, 'UnknownFilter', { minCases: 1 });
+    expect(all[0].total).toBe(3);
+    const post = retrieveCasesByCheck(store, 'UnknownFilter', { minCases: 1, since: MID });
+    expect(post[0].total).toBe(1);
+  });
+
+  test('ruleScores: ISO since filters emit + outcome counts', () => {
+    seedTwoEras();
+    const all = ruleScores(store, { minEmitted: 1 });
+    expect(all[0].emitted).toBe(3);
+    expect(all[0].total_outcomes).toBe(3);
+
+    const post = ruleScores(store, { minEmitted: 1, since: MID });
+    expect(post[0].emitted).toBe(1);
+    expect(post[0].total_outcomes).toBe(1);
+    expect(post[0].resolved).toBe(1);
+  });
+
+  test('ruleScores: since=null is the engine-state bypass', () => {
+    seedTwoEras();
+    store.setBaselineTs(MID);
+    // Default (meta-resolved) sees only post-baseline.
+    expect(ruleScores(store, { minEmitted: 1 })[0].emitted).toBe(1);
+    // Explicit bypass sees full history — this is what server.js +
+    // tools/server-status.js MUST pass for auto-disable / health snapshot.
+    expect(ruleScores(store, { minEmitted: 1, since: null })[0].emitted).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('ruleScores: meta baseline does NOT affect engine bypass call', () => {
+    // Belt-and-braces: even with a baseline set, since:null returns full data.
+    seedTwoEras();
+    store.setBaselineTs(NEW); // narrowest possible — would hide everything
+    const out = ruleScores(store, { minEmitted: 1, since: null });
+    expect(out[0].emitted).toBe(3);
+    store.clearBaseline();
+  });
+
+  test('suggestedRules: ISO since narrows candidate templates', () => {
+    // Seed a template whose post-baseline emits don't reach minCases — should
+    // disappear from suggestions when since=MID.
+    seedStore(store,
+      [
+        { fp: 'old-1', template_fp: 'tpl-old', check_name: 'OldOnlyCheck', hint_rule_id: 'unknown', ts: OLD },
+        { fp: 'old-2', template_fp: 'tpl-old', check_name: 'OldOnlyCheck', hint_rule_id: 'unknown', ts: OLD },
+        { fp: 'old-3', template_fp: 'tpl-old', check_name: 'OldOnlyCheck', hint_rule_id: 'unknown', ts: OLD },
+        { fp: 'old-4', template_fp: 'tpl-old', check_name: 'OldOnlyCheck', hint_rule_id: 'unknown', ts: OLD },
+        { fp: 'old-5', template_fp: 'tpl-old', check_name: 'OldOnlyCheck', hint_rule_id: 'unknown', ts: OLD },
+      ],
+      {
+        windows: [{ id: 1 }],
+        outcomes: [
+          { fp: 'old-1', outcome: 'resolved', fix_applied: 'verbatim' },
+          { fp: 'old-2', outcome: 'resolved', fix_applied: 'verbatim' },
+          { fp: 'old-3', outcome: 'resolved', fix_applied: 'verbatim' },
+          { fp: 'old-4', outcome: 'resolved', fix_applied: 'verbatim' },
+          { fp: 'old-5', outcome: 'resolved', fix_applied: 'verbatim' },
+        ],
+      }
+    );
+
+    const all = suggestedRules(store, new Set(), { minCases: 5, minResolutionRate: 0.5 });
+    expect(all.find(s => s.check === 'OldOnlyCheck')).toBeDefined();
+
+    const post = suggestedRules(store, new Set(), { minCases: 5, minResolutionRate: 0.5, since: MID });
+    expect(post.find(s => s.check === 'OldOnlyCheck')).toBeUndefined();
+  });
+
+  test('synthesizeGuardPredicate: ISO since narrows the inferred file_type set', () => {
+    // 5+ pages (would induce file_type=pages), then 0 post-baseline → no guard.
+    const diags = [];
+    for (let i = 0; i < 6; i++) {
+      diags.push({
+        fp: `g-${i}`, template_fp: 'tplG', check_name: 'GuardCheck',
+        file: `app/views/pages/p${i}.liquid`, ts: OLD, hint_rule_id: 'GuardCheck.r',
+      });
+    }
+    seedStore(store, diags, { windows: [], outcomes: [] });
+
+    // classifyFileType returns the singular form ('page', not 'pages').
+    const all = synthesizeGuardPredicate(store, 'GuardCheck', 'tplG', { minSamples: 5 });
+    expect(all.file_type).toBe('page');
+
+    const post = synthesizeGuardPredicate(store, 'GuardCheck', 'tplG', { minSamples: 5, since: MID });
+    expect(post.file_type).toBeUndefined();
+  });
+
+  test('scoreRule: NO since parameter — always sees full history', () => {
+    // scoreRule's signature deliberately has no since param. Even after the
+    // operator sets a baseline, scoreRule sees the full case set so live
+    // confidence-adjustment never deteriorates from a narrow window.
+    seedTwoEras();
+    store.setBaselineTs(NEW);
+    const adj = scoreRule(store, 'UnknownFilter.typo', 'tpl1');
+    expect(adj).not.toBeNull();
+    // 3 cases, 1 resolved, 2 regressed → regression rate 0.67 → harmful adjustment
+    expect(adj.adjustment).toBeLessThan(0);
+    store.clearBaseline();
+  });
+});
diff --git a/tests/unit/diagnostic-pipeline.test.js b/tests/unit/diagnostic-pipeline.test.js
index 9526fee..5ef2d92 100644
--- a/tests/unit/diagnostic-pipeline.test.js
+++ b/tests/unit/diagnostic-pipeline.test.js
@@ -758,3 +758,248 @@ describe('stampDefaultsOn: late-push diagnostics get default confidence', () =>
     expect(result.errors[0].rule_id).toBe('UnknownFilter.typo');
   });
 });
+
+// ── suppressLspKnownFalsePositives ──────────────────────────────────────────
+//
+// Pins the LSP "Syntax is not supported" suppression on `assign x = a  b`
+// boolean comparisons. Upstream pos-cli LSP rejects this construct even
+// though `pos-cli check run` and the platformOS Liquid parser both accept
+// it. Without the suppression, agents are forced to rewrite valid code as a
+// multi-line if/else just to clear the must_fix_before_write gate.
+
+describe('diagnostic-pipeline: suppressLspKnownFalsePositives', () => {
+  function syntaxErr(line, message = 'Syntax is not supported') {
+    return { check: 'LiquidHTMLSyntaxError', severity: 'error', line, message };
+  }
+
+  it('suppresses the LSP false positive on `assign x = a == b` when the file parses cleanly', () => {
+    const content = [
+      '{% doc %}',
+      '  @param {object} object',
+      '{% enddoc %}',
+      '{% liquid',
+      '  assign c = object.errors | default: empty',
+      '  assign object.valid = c == empty',
+      '  return object',
+      '%}',
+    ].join('\n');
+
+    const result = makeResult([syntaxErr(6)]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/lib/commands/contacts/create/check.liquid',
+      content,
+    });
+
+    expect(result.errors).toHaveLength(0);
+    const info = result.infos.find(i => i.check === 'pos-supervisor:LspSyntaxFalsePositiveSuppressed');
+    expect(info).toBeDefined();
+    expect(info.message).toContain('line(s) 6');
+    expect(info.message).toContain('@platformos/liquid-html-parser');
+  });
+
+  it('suppresses every "Syntax is not supported" diagnostic in the same file at once', () => {
+    const content = [
+      '{% liquid',
+      '  assign a = 1 == 1',
+      '  assign b = 2 != 3',
+      '%}',
+    ].join('\n');
+
+    const result = makeResult([syntaxErr(2), syntaxErr(3)]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/check.liquid',
+      content,
+    });
+
+    expect(result.errors).toHaveLength(0);
+    const info = result.infos.find(i => i.check === 'pos-supervisor:LspSyntaxFalsePositiveSuppressed');
+    expect(info.message).toContain('line(s) 2, 3');
+  });
+
+  it('does NOT suppress when the file has a real syntax error elsewhere (parser fails)', () => {
+    const content = [
+      '{% liquid',
+      '  assign x = 1 == 1',
+      '%}',
+      '{% if foo %}',
+      '  hello',
+      '{# missing endif — strict parse fails here #}',
+    ].join('\n');
+
+    const result = makeResult([syntaxErr(2)]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/broken.liquid',
+      content,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].check).toBe('LiquidHTMLSyntaxError');
+    expect(result.infos.some(i => i.check === 'pos-supervisor:LspSyntaxFalsePositiveSuppressed')).toBe(false);
+  });
+
+  it('does NOT suppress LiquidHTMLSyntaxError diagnostics with a different upstream message', () => {
+    const content = [
+      '{% liquid',
+      '  assign x = 1',
+      '%}',
+    ].join('\n');
+
+    const result = makeResult([
+      { check: 'LiquidHTMLSyntaxError', severity: 'error', line: 1, message: "Invalid syntax for tag 'render'" },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/x.liquid',
+      content,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:LspSyntaxFalsePositiveSuppressed')).toBe(false);
+  });
+
+  it('does NOT suppress non-LiquidHTMLSyntaxError checks even when the message text matches', () => {
+    const content = '{% liquid\n  assign x = 1\n%}\n';
+
+    const result = makeResult([
+      { check: 'UnknownFilter', severity: 'error', line: 1, message: 'Syntax is not supported' },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/x.liquid',
+      content,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].check).toBe('UnknownFilter');
+  });
+
+  it('also handles diagnostics surfaced as warnings, not just errors', () => {
+    const content = '{% liquid\n  assign x = 1 == 1\n%}\n';
+
+    const result = makeResult([], [
+      { check: 'LiquidHTMLSyntaxError', severity: 'warning', line: 2, message: 'Syntax is not supported' },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/x.liquid',
+      content,
+    });
+
+    expect(result.warnings).toHaveLength(0);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:LspSyntaxFalsePositiveSuppressed')).toBe(true);
+  });
+});
+
+// ── verifyPageRoutesOnDisk: in-memory file overlay ──────────────────────────
+//
+// Pins the self-page suppression: when an agent runs validate_code on a
+// page whose in-memory frontmatter declares the very (slug, method) pair
+// the LSP is complaining about, the route index must reflect the
+// in-memory version, not the older on-disk one. Without this overlay the
+// agent sees a MissingPage warning for a route the file IS about to serve
+// the moment it lands on disk — exactly the false positive observed in
+// the DEMO project (POST `/` warning while `app/views/pages/index.liquid`
+// declared `method: post` in-memory).
+
+describe('diagnostic-pipeline: verifyPageRoutesOnDisk respects in-memory overlay', () => {
+  let tmpDir;
+
+  beforeAll(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'pipeline-route-overlay-'));
+    mkdirSync(join(tmpDir, 'app/views/pages'), { recursive: true });
+    // Disk version: GET / only — no method declared.
+    writeFileSync(
+      join(tmpDir, 'app/views/pages/index.liquid'),
+      '
        old version (no frontmatter)
        \n',
+      'utf8',
+    );
+  });
+
+  afterAll(() => { if (tmpDir) rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it("suppresses MissingPage for route '/' (POST) when the file under validation declares method: post in-memory", () => {
+    const inMemory = [
+      '---',
+      'method: post',
+      'metadata:',
+      '  title: "Home"',
+      '---',
+      '
        POST handler in-memory
        ',
+    ].join('\n');
+
+    const result = makeResult([], [
+      { check: 'MissingPage', severity: 'warning', line: 6, column: 0, message: "No page found for route '/' (POST)" },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/pages/index.liquid',
+      content: inMemory,
+      projectDir: tmpDir,
+    });
+
+    expect(result.warnings).toHaveLength(0);
+    expect(result.infos.some(i => i.check === 'pos-supervisor:MissingPageSuppressed')).toBe(true);
+  });
+
+  it('still flags MissingPage when the in-memory frontmatter does not cover the reported method', () => {
+    const inMemory = [
+      '---',
+      'method: get',
+      '---',
+      '
        GET only
        ',
+    ].join('\n');
+
+    const result = makeResult([], [
+      { check: 'MissingPage', severity: 'warning', line: 4, column: 0, message: "No page found for route '/' (POST)" },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/pages/index.liquid',
+      content: inMemory,
+      projectDir: tmpDir,
+    });
+
+    expect(result.warnings).toHaveLength(1);
+    // wrong-method enrichment — the route IS served, just for GET.
+    expect(result.warnings[0].hint).toContain('GET');
+  });
+
+  it('treats a brand-new page (not yet on disk) as serving its declared route', () => {
+    const inMemory = [
+      '---',
+      'slug: contact',
+      'method: post',
+      '---',
+      '
        new page
        ',
+    ].join('\n');
+
+    const result = makeResult([], [
+      { check: 'MissingPage', severity: 'warning', line: 5, column: 0, message: "No page found for route '/contact' (POST)" },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/pages/contact.liquid',
+      content: inMemory,
+      projectDir: tmpDir,
+    });
+
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('ignores the overlay when the file under validation is not under app/views/pages/ (partial / layout)', () => {
+    // A partial cannot serve a route. Even if it has frontmatter (it shouldn't),
+    // the route index must remain disk-only for non-page files.
+    const inMemory = [
+      '---',
+      'slug: pretend',
+      'method: post',
+      '---',
+      '
        partial pretending to be a page
        ',
+    ].join('\n');
+
+    const result = makeResult([], [
+      { check: 'MissingPage', severity: 'warning', line: 5, column: 0, message: "No page found for route '/pretend' (POST)" },
+    ]);
+    runDiagnosticPipeline(result, {
+      filePath: 'app/views/partials/pretend.liquid',
+      content: inMemory,
+      projectDir: tmpDir,
+    });
+
+    expect(result.warnings).toHaveLength(1);
+  });
+});
diff --git a/tests/unit/http-handler-arity.test.js b/tests/unit/http-handler-arity.test.js
new file mode 100644
index 0000000..517b039
--- /dev/null
+++ b/tests/unit/http-handler-arity.test.js
@@ -0,0 +1,158 @@
+/**
+ * Static guard against the "caller passes the wrong number of args to an
+ * analytics handler" class of bug.
+ *
+ * Phase 5 (`since` parameter wiring) widened the signatures of three
+ * analytics handlers (`handleFixAdoptionFunnel`, `handleKnowledgeGaps`,
+ * `handleRuleHeatmap`) from `(store, res)` to `(store, url, res)`. Two
+ * other handlers were never widened during a follow-up review
+ * (`handleAnalyticsSessions`, `handleSuggestedRules`), and the matching
+ * call sites silently passed `(store, res)`. Bun runtime then evaluates
+ * `sendJson(res, ...)` with `res === undefined`, which throws a
+ * `TypeError: undefined is not an object (evaluating 'res.writeHead')` —
+ * the entire HTTP listener dies inside the request handler, leaving the
+ * MCP stdio process alive but the dashboard offline.
+ *
+ * The unit-test surface for that bug is awkward (handlers take real
+ * `req`/`res` streams). A static-source check is cheap, deterministic,
+ * and covers every analytics handler at once: read http-server.js as
+ * text, extract every handler's parameter count from its declaration,
+ * extract every call site's argument count from `return handleX(...)`,
+ * and assert they match.
+ *
+ * If you add a new handler, you don't need to touch this test — it
+ * discovers handlers + call sites by pattern.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = readFileSync(
+  join(import.meta.dir, '..', '..', 'src', 'http-server.js'),
+  'utf8',
+);
+
+/**
+ * Parse "function handleX(a, b, c) { ... }" declarations.
+ * Returns Map. Async-function declarations
+ * are supported; rest params (...x) are intentionally counted as 1
+ * because we don't dispatch with spread syntax.
+ */
+function extractHandlerArities(src) {
+  const re = /function\s+(handle[A-Za-z]+)\s*\(([^)]*)\)/g;
+  const out = new Map();
+  let m;
+  while ((m = re.exec(src))) {
+    const name = m[1];
+    const paramList = m[2].trim();
+    const arity = paramList === '' ? 0 : paramList.split(',').filter(Boolean).length;
+    out.set(name, arity);
+  }
+  return out;
+}
+
+/**
+ * Parse "return handleX(a, b, c)" call sites. Tolerates whitespace and
+ * matches up to the closing paren on the same line — every analytics
+ * dispatch is a single-line return.
+ */
+function extractCallSites(src) {
+  const re = /return\s+(handle[A-Za-z]+)\s*\(([^)]*)\)/g;
+  const out = [];
+  let m;
+  while ((m = re.exec(src))) {
+    const name = m[1];
+    const argList = m[2].trim();
+    const arity = argList === '' ? 0 : argList.split(',').filter(Boolean).length;
+    // Compute the source line for nicer test failures.
+    const line = src.slice(0, m.index).split('\n').length;
+    out.push({ name, arity, line });
+  }
+  return out;
+}
+
+describe('http-server.js handler dispatch arity', () => {
+  const arities = extractHandlerArities(SRC);
+  const callSites = extractCallSites(SRC);
+
+  test('handler declarations are discovered', () => {
+    // Sanity check the parser — http-server is large enough that we
+    // expect dozens of analytics handlers. If this drops to zero, the
+    // regex broke and the rest of the suite is silently green-on-zero.
+    expect(arities.size).toBeGreaterThan(20);
+  });
+
+  test('every analytics call site uses the declared arity', () => {
+    // Restrict to analytics handlers — the other handlers in this file
+    // have varied signatures (some take projectDir, some take body,
+    // etc.) and aren't part of the Phase 5 surface this guard protects.
+    const ANALYTICS_PREFIXES = [
+      'handleAnalytics',
+      'handleRule',
+      'handleFixRule',
+      'handleConfidence',
+      'handleFixAdoption',
+      'handleKnowledge',
+      'handleDiagnostic',
+      'handleSuggested',
+      'handleCases',
+    ];
+    const isAnalyticsHandler = (name) =>
+      ANALYTICS_PREFIXES.some(prefix => name.startsWith(prefix));
+
+    const mismatches = [];
+    for (const { name, arity, line } of callSites) {
+      if (!isAnalyticsHandler(name)) continue;
+      const declared = arities.get(name);
+      if (declared == null) continue; // imported handler — not declared in this file
+      if (declared !== arity) {
+        mismatches.push(
+          `http-server.js:${line} — return ${name}(...) passes ${arity} args, but ${name}() declares ${declared} parameters`,
+        );
+      }
+    }
+    expect(mismatches).toEqual([]);
+  });
+
+  test('every analytics handler that takes `url` actually uses it', () => {
+    // Belt-and-braces: catch the inverse — a handler whose signature
+    // declares (store, url, res) but whose body never references `url`
+    // is a dead parameter that probably indicates a broken refactor.
+    const ANALYTICS_NAMES = [...arities.keys()].filter(n =>
+      n.startsWith('handleAnalytics') ||
+      n.startsWith('handleRule') ||
+      n.startsWith('handleFixRule') ||
+      n.startsWith('handleConfidence') ||
+      n.startsWith('handleFixAdoption') ||
+      n.startsWith('handleKnowledge') ||
+      n.startsWith('handleDiagnostic') ||
+      n.startsWith('handleSuggested') ||
+      n.startsWith('handleCases')
+    );
+    const dead = [];
+    for (const name of ANALYTICS_NAMES) {
+      // Find the function body — slice from declaration to end of file
+      // and stop at the next top-level `function ` declaration.
+      const declRe = new RegExp(`function\\s+${name}\\s*\\(([^)]*)\\)`);
+      const declMatch = SRC.match(declRe);
+      if (!declMatch) continue;
+      const params = declMatch[1].split(',').map(p => p.trim()).filter(Boolean);
+      if (!params.includes('url')) continue; // doesn't take url — skip
+
+      const startIdx = declMatch.index + declMatch[0].length;
+      const restOfFile = SRC.slice(startIdx);
+      // Function body ends at the next "\n}\n\n" sequence or next "function "
+      // declaration at column 0. The simpler heuristic: look for "\nfunction "
+      // and slice up to it.
+      const nextDeclIdx = restOfFile.search(/\nfunction\s+\w/);
+      const body = nextDeclIdx >= 0 ? restOfFile.slice(0, nextDeclIdx) : restOfFile;
+
+      // Use \burl\b to avoid matching "url" as part of another identifier.
+      if (!/\burl\b/.test(body)) {
+        dead.push(`${name} declares 'url' parameter but body never references it`);
+      }
+    }
+    expect(dead).toEqual([]);
+  });
+});
diff --git a/tests/unit/http-since-param.test.js b/tests/unit/http-since-param.test.js
new file mode 100644
index 0000000..c3d2fff
--- /dev/null
+++ b/tests/unit/http-since-param.test.js
@@ -0,0 +1,63 @@
+/**
+ * Unit tests for `parseSinceParam` — the HTTP-side translator that maps
+ * the `?since=` query parameter to the tri-state contract used by
+ * analytics-queries + case-base reporting paths.
+ *
+ * The parser sits at the HTTP boundary. Integration tests can't cover it
+ * cleanly because the spawned-Node server can't open `bun:sqlite`, so the
+ * analytics endpoints return 503 in that environment. A unit test on the
+ * pure parser pins the contract every endpoint depends on.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { parseSinceParam } from '../../src/http-server.js';
+
+function urlWith(qs) {
+  return new URL(`http://localhost/foo${qs}`);
+}
+
+describe('parseSinceParam tri-state contract', () => {
+  test('absent ?since → undefined (meta default applies)', () => {
+    expect(parseSinceParam(urlWith(''))).toBeUndefined();
+    expect(parseSinceParam(urlWith('?other=1'))).toBeUndefined();
+  });
+
+  test('empty ?since → undefined', () => {
+    expect(parseSinceParam(urlWith('?since='))).toBeUndefined();
+  });
+
+  test('?since=all → null (engine-state bypass marker)', () => {
+    expect(parseSinceParam(urlWith('?since=all'))).toBeNull();
+  });
+
+  test('?since= → the same ISO string', () => {
+    const ts = '2026-04-30T12:00:00.000Z';
+    expect(parseSinceParam(urlWith(`?since=${encodeURIComponent(ts)}`))).toBe(ts);
+  });
+
+  test('?since= throws a 400-eligible Error', () => {
+    // The thrown message must include "since must be" so http-server.js's
+    // sinceErrorStatus() routes it as 400 rather than 500.
+    expect(() => parseSinceParam(urlWith('?since=not-a-date'))).toThrow(/since must be/);
+  });
+
+  test('whitespace-only ?since is rejected', () => {
+    // Date('   ') parses NaN → must throw.
+    expect(() => parseSinceParam(urlWith('?since=%20%20%20'))).toThrow(/since must be/);
+  });
+
+  test('case-sensitivity: only literal "all" is the bypass', () => {
+    // 'All' / 'ALL' must NOT collapse to null — strict matching avoids
+    // accidental bypass from typos that happen to parse as a Date elsewhere.
+    expect(() => parseSinceParam(urlWith('?since=All'))).toThrow();
+    expect(() => parseSinceParam(urlWith('?since=ALL'))).toThrow();
+  });
+
+  test('non-ISO but Date-parseable strings are accepted (Date is lenient)', () => {
+    // `new Date('2026-04-30')` parses to a valid date. The parser only
+    // rejects strings that fail Date — it does not enforce strict ISO 8601.
+    // This matches existing analytics flexibility (the SQL filter just
+    // compares strings); pin the behaviour so it doesn't drift.
+    expect(parseSinceParam(urlWith('?since=2026-04-30'))).toBe('2026-04-30');
+  });
+});
diff --git a/tests/unit/page-route-index.test.js b/tests/unit/page-route-index.test.js
index 3a47ccb..d9e008c 100644
--- a/tests/unit/page-route-index.test.js
+++ b/tests/unit/page-route-index.test.js
@@ -180,4 +180,91 @@ describe('page-route-index', () => {
       expect(resolvePageRoute('/totally-unknown', 'get', index)).toEqual({ status: 'missing' });
     });
   });
+
+  describe('buildPageRouteIndex with overlay', () => {
+    it("substitutes the overlay's frontmatter for the on-disk version of the same file", () => {
+      // Disk version of dashboard.liquid has no method (defaults to GET).
+      // Overlay declares `method: post` — the route's method set must reflect
+      // the overlay (POST), not the disk (GET).
+      const overlay = {
+        filePath: 'app/views/pages/dashboard.liquid',
+        content: '---\nmethod: post\n---\n
        POST handler
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      const methods = routes.get('dashboard');
+      expect(methods).toBeDefined();
+      expect(methods.has('post')).toBe(true);
+      expect(methods.has('get')).toBe(false);
+    });
+
+    it('adds a brand-new page (not yet on disk) to the index', () => {
+      const overlay = {
+        filePath: 'app/views/pages/contact.liquid',
+        content: '---\nmethod: post\n---\n
        new page
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('contact')).toBe(true);
+      expect(routes.get('contact').has('post')).toBe(true);
+    });
+
+    it("respects the overlay's frontmatter slug just like it does for on-disk files", () => {
+      const overlay = {
+        filePath: 'app/views/pages/whatever.liquid',
+        content: '---\nslug: my-custom-route\nmethod: put\n---\n
        x
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('my-custom-route')).toBe(true);
+      expect(routes.has('whatever')).toBe(false);
+    });
+
+    it('accepts an absolute filePath in the overlay', () => {
+      const overlay = {
+        filePath: join(tmpDir, 'app/views/pages/contact.liquid'),
+        content: '---\nmethod: post\n---\n
        x
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('contact')).toBe(true);
+    });
+
+    it('ignores the overlay when the file is not under app/views/pages/', () => {
+      // Partials cannot serve routes. The overlay must be silently dropped
+      // rather than creating a phantom route entry.
+      const overlay = {
+        filePath: 'app/views/partials/header.liquid',
+        content: '---\nslug: phantom\nmethod: post\n---\n
        x
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('phantom')).toBe(false);
+    });
+
+    it('ignores the overlay when filePath does not end in .liquid', () => {
+      const overlay = {
+        filePath: 'app/views/pages/contact.json.liquid.bak',
+        content: '---\nslug: phantom\n---\n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('phantom')).toBe(false);
+    });
+
+    it('treats a malformed overlay (missing fields) as if no overlay were provided', () => {
+      const baseline = buildPageRouteIndex(tmpDir).routes.size;
+      expect(buildPageRouteIndex(tmpDir, null).routes.size).toBe(baseline);
+      expect(buildPageRouteIndex(tmpDir, {}).routes.size).toBe(baseline);
+      expect(buildPageRouteIndex(tmpDir, { filePath: 'x' }).routes.size).toBe(baseline);
+      expect(buildPageRouteIndex(tmpDir, { content: 'x' }).routes.size).toBe(baseline);
+    });
+
+    it('overlay with no frontmatter falls back to path-derived route + GET', () => {
+      // The disk version of dashboard.liquid is also no-frontmatter / GET.
+      // Overlay just confirms the same. Ensures empty frontmatter does not
+      // accidentally erase the file from the index.
+      const overlay = {
+        filePath: 'app/views/pages/dashboard.liquid',
+        content: '
        no frontmatter
        \n',
+      };
+      const { routes } = buildPageRouteIndex(tmpDir, overlay);
+      expect(routes.has('dashboard')).toBe(true);
+      expect(routes.get('dashboard').has('get')).toBe(true);
+    });
+  });
 });
diff --git a/tests/unit/rules/MissingPartial.test.js b/tests/unit/rules/MissingPartial.test.js
index 732077c..2fef604 100644
--- a/tests/unit/rules/MissingPartial.test.js
+++ b/tests/unit/rules/MissingPartial.test.js
@@ -325,16 +325,21 @@ describe('MissingPartial.invalid_lib_prefix', () => {
 });
 
 describe('MissingPartial — edge cases', () => {
-  test('returns null when partial param is missing', () => {
+  test('falls through to .default when partial param is missing (was .unmatched before catch-all)', () => {
     const diag = { check: 'MissingPartial', params: {} };
     const result = runRules(diag, facts);
-    expect(result).toBeNull();
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('MissingPartial.default');
+    // No symbol name in the hint when extraction failed.
+    expect(result.hint_md).toContain('this reference');
+    expect(result.hint_md).not.toContain('``');  // no empty backticked symbol
   });
 
-  test('returns null when params is undefined', () => {
+  test('falls through to .default when params is undefined', () => {
     const diag = { check: 'MissingPartial' };
     const result = runRules(diag, facts);
-    expect(result).toBeNull();
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('MissingPartial.default');
   });
 
   test('rule_id is always set in result', () => {
@@ -345,3 +350,51 @@ describe('MissingPartial — edge cases', () => {
     expect(result.rule_id.startsWith('MissingPartial.')).toBe(true);
   });
 });
+
+describe('MissingPartial.default catch-all', () => {
+  test('does NOT preempt a more specific rule (priority order intact)', () => {
+    const diag = {
+      check: 'MissingPartial',
+      params: { partial: 'lib/commands/orders/create' },
+      line: 3, column: 12, endLine: 3, endColumn: 41,
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.invalid_lib_prefix');
+  });
+
+  test('does NOT preempt MissingPartial.module_path', () => {
+    const diag = { check: 'MissingPartial', params: { partial: 'modules/user/helpers/auth' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.module_path');
+  });
+
+  test('emits the partial name in the hint when extractParams found one', () => {
+    const diag = {
+      check: 'MissingPartial',
+      // Path that doesn't match any specialised guard: not modules/, not lib/,
+      // not file_exists, no levenshtein neighbours, classifyPath says nothing
+      // useful → .default catches it.
+      params: { partial: 'completely/unrecognisable/shape/that/no/specialised/rule/wants' },
+    };
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    // Either a more specific rule fires (acceptable) or the default carries
+    // the symbol name. The contract is "every emit gets a typed rule_id".
+    expect(result.rule_id.startsWith('MissingPartial.')).toBe(true);
+    expect(result.rule_id).not.toBe('MissingPartial.unmatched');
+  });
+
+  test('default rule confidence is intentionally lower than the named guards', () => {
+    const diag = { check: 'MissingPartial' };  // no params at all
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('MissingPartial.default');
+    expect(result.confidence).toBeLessThanOrEqual(0.6);
+  });
+
+  test('default emits a project_map see_also so the agent has a recovery path', () => {
+    const diag = { check: 'MissingPartial', params: {} };
+    const result = runRules(diag, facts);
+    expect(result.see_also).toBeDefined();
+    expect(result.see_also.tool).toBe('project_map');
+  });
+});
diff --git a/tests/unit/rules/TranslationKeyExists.test.js b/tests/unit/rules/TranslationKeyExists.test.js
index 9ae6a47..1b67450 100644
--- a/tests/unit/rules/TranslationKeyExists.test.js
+++ b/tests/unit/rules/TranslationKeyExists.test.js
@@ -113,9 +113,51 @@ describe('TranslationKeyExists.array_index_misuse', () => {
 });
 
 describe('TranslationKeyExists — edge cases', () => {
-  test('returns null when key param is missing', () => {
+  test('falls through to .default when key param is missing', () => {
     const diag = { check: 'TranslationKeyExists', params: {} };
-    expect(runRules(diag, facts)).toBeNull();
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('TranslationKeyExists.default');
+  });
+});
+
+describe('TranslationKeyExists.default catch-all', () => {
+  test('does NOT preempt .array_index_misuse', () => {
+    const diag = {
+      check: 'TranslationKeyExists',
+      params: { key: 'app.title[0]' },
+      message: "'app.title[0]' does not have a matching translation entry",
+    };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('TranslationKeyExists.array_index_misuse');
+  });
+
+  test('does NOT preempt .suggest_nearest', () => {
+    const diag = { check: 'TranslationKeyExists', params: { key: 'app.titl' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('TranslationKeyExists.suggest_nearest');
+  });
+
+  test('does NOT preempt .create_key for a brand-new key with no near matches', () => {
+    const diag = { check: 'TranslationKeyExists', params: { key: 'a.completely.disjoint.brand_new.key' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('TranslationKeyExists.create_key');
+  });
+
+  test('fires when extraction failed entirely', () => {
+    const diag = { check: 'TranslationKeyExists' };
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('TranslationKeyExists.default');
+    expect(result.confidence).toBeLessThanOrEqual(0.5);
+  });
+
+  test('hint warns against locale-prefix typos and points at app/translations/', () => {
+    const diag = { check: 'TranslationKeyExists' };
+    const result = runRules(diag, facts);
+    expect(result.hint_md).toContain('app/translations/');
+    expect(result.hint_md).toContain('| t');
+    expect(result.hint_md).toContain('locale');
   });
 });
 
diff --git a/tests/unit/rules/UndefinedObject.test.js b/tests/unit/rules/UndefinedObject.test.js
index 9caacc5..0c350af 100644
--- a/tests/unit/rules/UndefinedObject.test.js
+++ b/tests/unit/rules/UndefinedObject.test.js
@@ -91,8 +91,52 @@ describe('UndefinedObject.generic', () => {
 });
 
 describe('UndefinedObject — edge cases', () => {
-  test('returns null when variable param is missing', () => {
+  test('falls through to .default when variable param is missing', () => {
     const diag = { check: 'UndefinedObject', params: {} };
-    expect(runRules(diag, facts)).toBeNull();
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('UndefinedObject.default');
+  });
+});
+
+describe('UndefinedObject.default catch-all', () => {
+  test('does NOT preempt .shopify_object', () => {
+    const diag = { check: 'UndefinedObject', params: { variable: 'product' }, file: 'app/views/pages/index.html.liquid' };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UndefinedObject.shopify_object');
+  });
+
+  test('does NOT preempt .context_prefix', () => {
+    const diag = { check: 'UndefinedObject', params: { variable: 'params' }, file: 'app/views/pages/index.html.liquid' };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UndefinedObject.context_prefix');
+  });
+
+  test('does NOT preempt .declare_param in partials', () => {
+    const diag = { check: 'UndefinedObject', params: { variable: 'props' }, file: 'app/views/partials/header.liquid' };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UndefinedObject.declare_param');
+  });
+
+  test('does NOT preempt .generic when variable is extracted', () => {
+    const diag = { check: 'UndefinedObject', params: { variable: 'xyz' }, file: 'app/views/pages/index.html.liquid' };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UndefinedObject.generic');
+  });
+
+  test('fires when extraction failed entirely (no params, no file)', () => {
+    const diag = { check: 'UndefinedObject' };
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('UndefinedObject.default');
+    expect(result.confidence).toBeLessThan(0.5);
+  });
+
+  test('hint covers the three canonical resolutions (page / partial / local)', () => {
+    const diag = { check: 'UndefinedObject', params: {} };
+    const result = runRules(diag, facts);
+    expect(result.hint_md).toContain('context.');
+    expect(result.hint_md).toContain('@param');
+    expect(result.hint_md).toContain('assign');
   });
 });
diff --git a/tests/unit/rules/UnknownFilter.test.js b/tests/unit/rules/UnknownFilter.test.js
index 5b0aae2..13dcf61 100644
--- a/tests/unit/rules/UnknownFilter.test.js
+++ b/tests/unit/rules/UnknownFilter.test.js
@@ -74,9 +74,58 @@ describe('UnknownFilter.generic', () => {
 });
 
 describe('UnknownFilter — edge cases', () => {
-  test('returns null when filter param is missing', () => {
+  test('falls through to .default when filter param is missing', () => {
     const facts = { graph, tagsIndex: mockTagsIndex, filtersIndex: mockFiltersIndex };
     const diag = { check: 'UnknownFilter', params: {} };
-    expect(runRules(diag, facts)).toBeNull();
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('UnknownFilter.default');
+  });
+});
+
+describe('UnknownFilter.default catch-all', () => {
+  test('does NOT preempt .tag_confusion', () => {
+    const facts = { graph, tagsIndex: mockTagsIndex, filtersIndex: mockFiltersIndex };
+    const diag = { check: 'UnknownFilter', params: { filter: 'render' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UnknownFilter.tag_confusion');
+  });
+
+  test('does NOT preempt .shopify_filter', () => {
+    const facts = { graph, tagsIndex: mockTagsIndex, filtersIndex: mockFiltersIndex };
+    const diag = { check: 'UnknownFilter', params: { filter: 'money' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UnknownFilter.shopify_filter');
+  });
+
+  test('does NOT preempt .suggest_nearest', () => {
+    const facts = { graph, tagsIndex: { isTag: () => false }, filtersIndex: mockFiltersIndex };
+    const diag = { check: 'UnknownFilter', params: { filter: 'downcase' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UnknownFilter.suggest_nearest');
+  });
+
+  test('does NOT preempt .generic when filter name was extracted', () => {
+    const noMatchIndex = { loaded: true, lookup: () => null, closestMatch: () => null };
+    const facts = { graph, tagsIndex: { isTag: () => false }, filtersIndex: noMatchIndex };
+    const diag = { check: 'UnknownFilter', params: { filter: 'zzz_nonexistent' } };
+    const result = runRules(diag, facts);
+    expect(result.rule_id).toBe('UnknownFilter.generic');
+  });
+
+  test('fires when extraction failed entirely', () => {
+    const facts = { graph, tagsIndex: mockTagsIndex, filtersIndex: mockFiltersIndex };
+    const diag = { check: 'UnknownFilter' };
+    const result = runRules(diag, facts);
+    expect(result).not.toBeNull();
+    expect(result.rule_id).toBe('UnknownFilter.default');
+  });
+
+  test('hint covers typo + Shopify-only escape hatches', () => {
+    const facts = { graph, tagsIndex: mockTagsIndex, filtersIndex: mockFiltersIndex };
+    const diag = { check: 'UnknownFilter', params: {} };
+    const result = runRules(diag, facts);
+    expect(result.hint_md).toContain('lookup');
+    expect(result.hint_md).toContain('Shopify');
   });
 });
diff --git a/tests/unit/unknown-property-rules.test.js b/tests/unit/unknown-property-rules.test.js
index 887ca51..b3a99d9 100644
--- a/tests/unit/unknown-property-rules.test.js
+++ b/tests/unit/unknown-property-rules.test.js
@@ -173,7 +173,7 @@ describe('UnknownProperty rules', () => {
       expect(result.hint_md).toContain('doc');
     });
 
-    it('returns null when params are missing', () => {
+    it('falls through to .default when params are missing', () => {
       const graph = buildMinimalGraph();
       const diag = {
         check: 'UnknownProperty',
@@ -182,7 +182,81 @@ describe('UnknownProperty rules', () => {
         file: 'test.liquid',
       };
       const result = runRules(diag, { graph });
-      expect(result).toBeNull();
+      expect(result).not.toBeNull();
+      expect(result.rule_id).toBe('UnknownProperty.default');
+    });
+  });
+
+  describe('default catch-all (priority 1000)', () => {
+    it('does NOT preempt .schema_property', () => {
+      const graph = buildGraphWithSchema();
+      const diag = {
+        check: 'UnknownProperty',
+        params: { property: 'tittle', object: 'blog_post' },
+        message: "Property 'tittle' does not exist on 'blog_post'",
+        file: 'app/views/pages/blog.liquid',
+      };
+      const result = runRules(diag, { graph });
+      expect(result.rule_id).toBe('UnknownProperty.schema_property');
+    });
+
+    it('does NOT preempt .context_property', () => {
+      const graph = buildMinimalGraph();
+      const objectsIndex = {
+        loaded: true,
+        contextObjects: () => [{ handle: 'context.current_user', properties: ['id', 'email'] }],
+      };
+      const diag = {
+        check: 'UnknownProperty',
+        params: { property: 'emai', object: 'context.current_user' },
+        message: "Property 'emai' does not exist on 'context.current_user'",
+        file: 'test.liquid',
+      };
+      const result = runRules(diag, { graph, objectsIndex });
+      expect(result.rule_id).toBe('UnknownProperty.context_property');
+    });
+
+    it('does NOT preempt .generic when both params are extracted', () => {
+      const graph = buildMinimalGraph();
+      const diag = {
+        check: 'UnknownProperty',
+        params: { property: 'foo', object: 'bar' },
+        message: "Property 'foo' does not exist on 'bar'",
+        file: 'test.liquid',
+      };
+      const result = runRules(diag, { graph });
+      expect(result.rule_id).toBe('UnknownProperty.generic');
+    });
+
+    it('fires when only one of property/object was extracted', () => {
+      const graph = buildMinimalGraph();
+      const diag = {
+        check: 'UnknownProperty',
+        params: { property: 'foo' },        // missing object
+        message: "Property 'foo' does not exist",
+        file: 'test.liquid',
+      };
+      const result = runRules(diag, { graph });
+      expect(result).not.toBeNull();
+      expect(result.rule_id).toBe('UnknownProperty.default');
+    });
+
+    it('fires when extraction failed entirely', () => {
+      const graph = buildMinimalGraph();
+      const diag = { check: 'UnknownProperty' };
+      const result = runRules(diag, { graph });
+      expect(result).not.toBeNull();
+      expect(result.rule_id).toBe('UnknownProperty.default');
+      expect(result.confidence).toBeLessThan(0.5);
+    });
+
+    it('hint covers typo / schema / partial-@param escape hatches', () => {
+      const graph = buildMinimalGraph();
+      const diag = { check: 'UnknownProperty' };
+      const result = runRules(diag, { graph });
+      expect(result.hint_md).toContain('schema');
+      expect(result.hint_md).toContain('@param');
+      expect(result.hint_md).toContain('lookup');
     });
   });
 });