@pan-stack/cli 0.3.30 → 0.3.32

package/dist/agent-plugin/plugins/pan-harness/skills/pan-harness/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pan-harness
+description: Cách làm việc trong workspace PAN Stack có pan-harness — danh tính người chủ quản/máy cho mọi thay đổi của AI, ghi nguồn tài liệu bằng Pan Lineage (pan lineage derive/why/diff/ack), commit tự ghi nhờ hook. Dùng khi sửa tệp dựa trên tài liệu BA (PRD/FSD/BDD), khi hook báo nguồn đã đổi, hoặc khi người dùng hỏi tệp này dựa vào tài liệu nào.
+---
+
+# pan-harness
+
+Harness đã làm sẵn phần lớn việc; agent chỉ giữ ba thói quen.
+
+## 1. Ghi nguồn khi sửa theo tài liệu
+
+Tệp bạn tạo hoặc sửa để hiện thực một mục tài liệu (FSD, BDD, quy tắc nghiệp vụ…) phải trỏ về mục đó:
+
+```bash
+pan lineage derive <tệp> --source <repo>:<đường dẫn tài liệu>#<khoá mục>
+```
+
+- Khoá mục: mã trong heading (`SCR-01.02-01`, `BR-01.02-03`, mã UC/TC) hoặc slug theo đường dẫn heading.
+  Không chắc khoá: `pan lineage impact <repo>:<tài liệu>` liệt kê các mục đang được dùng.
+- Tệp không phải markdown (YAML panui, mã) nhắc đúng mã có ở một mục duy nhất thì hook commit tự ghi — không cần derive.
+- Người ghi (AI, mã agent, model) đã được plugin đặt sẵn cho phiên; không cần thêm cờ.
+
+## 2. Khi harness báo "CẦN XEM LẠI"
+
+Tệp vừa đọc có nguồn đã đổi: harness kèm diff của đúng mục đó.
+
+1. Đọc diff, sửa tệp theo nguồn mới, rồi `pan lineage derive <tệp> --source <nguồn>` (ghi UPDATED).
+2. Thay đổi không ảnh hưởng tệp: `pan lineage ack <tệp> --source <nguồn> --reason "<lý do đủ để ba tháng sau đọc vẫn hiểu>"`.
+
+Không tự coi là đã cập nhật khi chưa đọc diff. Lằn ranh đỏ (quyền, mất dữ liệu, API dùng chung) thì hỏi người.
+
+## 3. Commit
+
+Hook `pan lineage hook pre-commit` tự stage `.pan-lineage/` vào cùng commit. Đọc dòng nó in ra: `⚠` là còn nguồn đã đổi,
+`?` là mã có ở nhiều mục — chọn bằng `pan lineage derive`. Chưa có danh tính người chủ quản thì nhắc người dùng chạy `pan me`.
+
+## 4. Rào, lint, cổng xong
+
+- Bị chặn (secret, giả làm người khi duyệt, subagent) là luật của workspace — làm cách khác hoặc hỏi người; không lách bằng biến môi trường.
+- Duyệt: một dấu OK là đủ, ai cũng được — kể cả AI (OD-51). Người dùng bảo duyệt thì `pan harness approve <pha> [--note "…"]`;
+  sổ tự ghi AI + người chủ quản + vai (`role:` của `.me.pan.yaml`) + máy. Không tự duyệt khi chưa được bảo.
+- Sau mỗi lần sửa, harness có thể nạp `[pan-harness] lint …` (luật `lint:` trong `.pan-harness.yaml`): sửa luôn vi phạm đó.
+- Trước khi báo xong: `pan harness status`; cổng ở phần vừa sửa chưa qua thì `pan harness check <pha>` tới khi xanh.
+- Workspace có dự án Pan Studio liên kết (khối `backend:` trong app.panui.yaml): chạy cổng bằng `pan harness check <pha> --push`
+  để cả đội (PM, BA không clone repo) thấy kết quả trên web Studio / Desktop — công bố cả khi đỏ.
+
+## 5. Program (OD-52)
+
+Workspace khai `studio: { program: <mã> }` trong `.project.yaml` thì harness tự báo nhịp tim agent lên bảng công trường của
+Program, và tự đẩy thay đổi Pan Plans lên (`pan program sync --auto` sau mỗi lệnh ghi `pan task|usecase|testcase|plan …`, khi
+bắt đầu phiên và khi agent dừng) — không cần tự gọi sync. Chỉ project con có `sync: on` trong `docs/projects/<KEY>/studio.yaml`
+mới gửi. Bị báo "bảng đang có bản mới hơn" thì `git pull` rồi `pan program sync`. Lỗi quyền / lần gửi cuối: `pan program status`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pan-stack/cli",
-  "version": "0.3.30",
+  "version": "0.3.32",
   "description": "PAN Stack CLI — multi-repo git and project commands from .project.yaml",
   "license": "SEE LICENSE IN LICENSE.txt",
   "bin": {
@@ -11,13 +11,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
-    "bin"
+    "bin",
+    "dist/agent-plugin"
   ],
   "scripts": {
     "build": "node tools/pan-stack-cli/build.mjs",
+    "build:agent-plugin": "node tools/pan-stack-cli/build-agent-plugin.ts",
     "prepare": "node tools/pan-stack-cli/build.mjs",
     "prepublishOnly": "node tools/pan-stack-cli/build.mjs",
-    "test": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p tools/pan-stack-plan/tsconfig.web.json --noEmit && tsc -p tools/pan-stack-plan/tsconfig.e2e.json --noEmit && node --test \"tools/pan-stack-plan/test/*.test.ts\" \"tools/pan-stack-cli/test/*.test.ts\" \"tools/pan-lineage/test/*.test.ts\" \"tools/pan-harness/test/*.test.ts\" \"tools/pan-program/test/*.test.ts\" && node --test \"tools/pan-cicd/test/*.test.mjs\"",
+    "test": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p tools/pan-stack-plan/tsconfig.web.json --noEmit && tsc -p tools/pan-stack-plan/tsconfig.e2e.json --noEmit && node --test \"tools/pan-stack-plan/test/*.test.ts\" \"tools/pan-stack-cli/test/*.test.ts\" \"tools/pan-lineage/test/*.test.ts\" \"tools/pan-harness/test/*.test.ts\" \"tools/pan-program/test/*.test.ts\" \"agent-plugin/plugins/pan-harness/test/*.test.mjs\" && node --test \"tools/pan-cicd/test/*.test.mjs\"",
     "test:pan-cicd": "node tools/pan-stack-cli/build.mjs && node --test \"tools/pan-cicd/test/*.test.mjs\"",
     "test:pan-stack-plan": "node --test \"tools/pan-stack-plan/test/*.test.ts\"",
     "test:pan-stack-cli": "node --test \"tools/pan-stack-cli/test/*.test.ts\"",