Skill: harness-tour

WHAT

Purpose và context

Purpose: Cho user THẤY (không phải đọc) harness hoạt động: bạn — Claude — cố tình vi phạm rule trên project thật, bị hook chặn theo thời gian thực, và tường thuật lại. Kết thúc không để lại rác.
Trigger (when to use): user gõ
```
/harness-tour
```
hoặc nói "harness tour", "xem harness làm gì", "test short", "test full" (
```
disable-model-invocation: true
```
— chỉ chạy khi user gọi). Hai độ dài: SHORT (mặc định, R1·R2·R3) và FULL (R1–R10).
Non-goals: không cài/sửa harness (chỉ gợi ý lệnh cài khi MISSING), không diễn giả khi không có hook, không đụng file có sẵn của project, không thay
```
demo.sh
```
/
```
test-broad.sh
```
(bản máy-diễn không cần phiên).

Mental model

ARGUMENTS → độ dài (SHORT|FULL) → pre-check harness (POC|PROD|MISSING) → mỗi cảnh: tường thuật → vi phạm có chủ đích trên path map 1-rule → hook chặn live → trích nguyên văn → khắc phục → dọn dẹp tour-demo* + row index cùng lượt → kết màn trích audit.jsonl

. Rule chia 3 nhóm: chặn-live (R1,R2,R3,R5,R7,R9) · ghi/nhắc không chặn (R4,R8,R10) · tầng repo (R6).

Input và output contract

	Field	Required?	Ý nghĩa
In	ARGUMENTS	không	chứa `full` / `10` /"đầy đủ" → FULL; còn lại → SHORT
In	session mở ở root project đã cài harness	có	`.claude/settings.json` phải được load, không thì MISSING
Out	tường thuật + stderr chặn trích nguyên văn mỗi cảnh	có	vd `[R1 no-write-raw] …` , `[R3 index-sync] …`
Out	project sạch	có	mọi `tour-demo*` đã PASS bị xoá + row index tương ứng; artifact harness giữ nguyên
Out	kết màn	có	tóm rule vừa chặn + `cat` vài dòng cuối `.claude/audit/*.jsonl` ; FULL thêm bảng 10 rule

Rules và capabilities

RULE-01 (MUST): Mỗi cảnh: tường thuật → vi phạm → trích nguyên văn lý do chặn → khắc phục. Không diễn tắt.
RULE-02 (MUST): Chỉ đụng file tên
```
tour-demo*
```
; tuyệt đối không sửa/xóa file có sẵn của project.
RULE-03 (MUST): Một cảnh đáng-lẽ-chặn mà KHÔNG bị chặn → dừng tour, báo "hàng rào hỏng ở rule X" — đó là bug thật cần xử lý (KHÔNG áp dụng cho nhóm không-chặn R4/R6/R8/R10 — chúng vốn không block).
Capabilities: ghi/xoá file demo
```
tour-demo*
```
trong
```
llmwiki/
```
+ sửa
```
wiki/index.md
```
(row demo); đọc artifact audit; chạy script harness cục bộ. Phụ thuộc hook của host (PreToolUse/Stop) — không có hook thì không diễn.

Failure boundaries

Pre-check không in gì → blocked (MISSING): DỪNG, gợi ý lệnh cài PoC + mở session mới tại root, không diễn giả.
Cảnh đáng-lẽ-chặn mà không bị chặn → failed: dừng tour, báo "hàng rào hỏng ở rule X" (trừ R4/R6/R8/R10).
Dọn dẹp xoá file mà sót row index → Stop hook R3 chặn chính lượt dọn → xoá row trong cùng lượt rồi kết thúc.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	ARGUMENTS	Chọn độ dài tour	SHORT hoặc FULL	—
W02	deterministic	root session	Pre-check harness (lệnh `grep` / `test` dưới)	POC / PROD	không in gì → MISSING, dừng
W03	effect	map path → rule	Diễn kịch bản SHORT (3 cảnh) hoặc FULL (R1–R10) tuần tự, tường thuật TRƯỚC mỗi cảnh	stderr chặn trích nguyên văn + file PASS	không bị chặn → dừng, báo hàng rào hỏng
W04	effect	file tour-demo* đã PASS	Dọn dẹp cùng một lượt: xoá file + row index	project sạch	Stop R3 chặn → xoá row còn sót
W05	deterministic	audit	Kết màn: tóm rule + `cat` `.claude/audit/*.jsonl`	báo cáo	—

Chi tiết từng bước (nguồn chân lý cho W01–W05):

Chọn độ dài tour (đọc ARGUMENTS)

Chứa
```
full
```
/
```
10
```
/ "đầy đủ" → FULL (R1–R10).
Còn lại (mặc định, hay
```
short
```
/
```
3
```
) → SHORT (3 cảnh: R1 · R2 · R3).

Pre-check — phát hiện harness nào đang sống trong session

Chạy ở ROOT của session:

bash

{ grep -q llmwiki-validate .claude/settings.json 2>/dev/null && test -f harness/poc-vendor-neutral/bin/llmwiki-validate.py && echo POC; }
test -f llmwiki/.claude/hooks/pre_tool_use.py && echo PROD

In POC
→ cách CHÍNH. PoC nay đủ R1–R10 (5 rule chặn ở PreToolUse + R3/R4/R8/R10 qua hook sự kiện).
In PROD
→ harness production. Cùng R1–R10, cùng kịch bản short/full dưới đây; chỉ khác tên hook script (
```
pre_tool_use.py
```
/
```
post_tool_use.py
```
/
```
stop.py
```
) và R1 có thể chặn qua
```
permissions.deny
```
. Diễn y hệt.
KHÔNG in gì → MISSING. DỪNG (đừng diễn giả), gợi ý cài (PoC là cách chính):
bash
```
curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/harness/poc-vendor-neutral/bootstrap.sh | bash
```
rồi mở session Claude MỚI tại root project đó (để
```
.claude/settings.json
```
được load) → gõ lại
```
/harness-tour
```
.

Hook chỉ chặn khi session load
.claude/settings.json
ở đúng root project đã cài. Mở session ở repo nguồn / root khác → không có hook → tour KHÔNG diễn (diễn mà không bị chặn = dàn dựng, cấm).

Harness là HOOK, KHÔNG phải MCP (giải thích nếu user hỏi "sao /mcp không thấy")

Lớp chặn là PreToolUse hook → kiểm bằng

/hooks

hoặc khối

hooks

trong

.claude/settings.json

, KHÔNG ở

/mcp

. MCP là thứ khác (tool cho model gọi). PoC: hook gọi

llmwiki-validate claude-hook

. Production:

pre_tool_use.py

…

Bảng map path → rule (DÙNG ĐÚNG path để mỗi cảnh chỉ kích 1 rule)

Nhiều rule cùng soi

wiki/

→ chọn sai path là 2 rule cùng chặn, rối. Map chuẩn (theo

policy.yaml

Rule	File để vi phạm	Vì sao CHỈ rule đó kích
R1 no-write-raw	`llmwiki/raw/tour-demo.md`	deny_write glob `raw/**`
R2 origin-required	`llmwiki/wiki/sources/draft/tour-demo.md` = `---\ntype: draft\n---\n# Tour Demo` (CÓ frontmatter, KHÔNG `## Origin` , KHÔNG `## Plan` )	frontmatter → R9 qua; thiếu Origin → R2 chặn
R3 index-sync	(Stop) chính file R2 vừa tạo, CHƯA có trong `wiki/index.md`	`m_stop` quét `concepts/entities/sources/draft` so với index
R5 folder-structure	`llmwiki/wiki/tour-demo.md` (ngay dưới `wiki/` , basename lạ)	forbid_root: `wiki/*.md` không thuộc allow-list
R7 proposal-complete	`llmwiki/wiki/sources/draft/tour-demo-proposal.md` — CÓ frontmatter + `## Origin` + `## Plan` + `proposed` , THIẾU `## Agent Task Assignment` & `Sequence diagram`	frontmatter→R9 qua, Origin→R2 qua → R7 là cái chặn
R9 okf-frontmatter	`llmwiki/wiki/concepts/tour-demo.md` — CÓ `## Origin` nhưng KHÔNG có YAML frontmatter	có Origin nên R2 qua; thiếu `type:` → R9 chặn

⚠️ R9 nay phủ CẢ
sources/
+
draft/
(khớp global production — nháp cũng cần frontmatter). Vì R2/R9 cùng soi mọi content dir → cô lập bằng NỘI DUNG, không bằng path: file CÓ frontmatter mà THIẾU Origin → chỉ R2; file CÓ Origin mà THIẾU frontmatter → chỉ R9.

Không-chặn-live (chỉ cho XEM artifact, nói rõ "không chặn"): R4 (

.claude/audit/audit.jsonl

log.md

), R8 (dòng

[harness] N rule…

lúc SessionStart), R10 (

.claude/audit/.docs-gate.json

đếm prompt). Tầng repo: R6 (pre-commit + CI

.github/workflows/harness.yml

+ skill

/verify-before-commit

KỊCH BẢN SHORT (mặc định) — 3 cảnh, diễn TUẦN TỰ, tường thuật TRƯỚC mỗi cảnh

Mở màn: "Tôi sẽ cố tình vi phạm 3 rule. Xem hook chặn tôi theo thời gian thực — không phải tôi tự nhường."

Cảnh 1 — R1 (PreToolUse · deny ghi raw/):

Tường thuật: "raw/ là inbox của con người, agent không được ghi."
Write
```
llmwiki/raw/tour-demo.md
```
→ exit 2 → CHẶN. Trích nguyên văn stderr
```
[R1 no-write-raw] …
```
. KHÔNG retry. File không ra đời.

Cảnh 2 — R2 (PreToolUse · ép
## Origin
):

Tường thuật: "Tạo file nguồn mà 'quên'
```
## Origin
```
→ không truy được gốc."

Write

llmwiki/wiki/sources/draft/tour-demo.md

---\ntype: draft\n---\n# Tour Demo

(CÓ frontmatter để R9 qua, nhưng KHÔNG có

## Origin

) → exit 2 → CHẶN. Trích

[R2 origin-required] …

Sửa: Write lại đúng file đó, thêm
```
## Origin\n- harness-tour demo
```
(giữ nguyên frontmatter) → lần này PASS, file được ghi.

Cảnh 3 — R3 (Stop · index nói dối):

Tường thuật: "File tour-demo vừa tạo nhưng tôi cố tình KHÔNG ghi nó vào
```
wiki/index.md
```
. Giờ thử kết thúc lượt."
Kết thúc response tại đây mà không cập nhật index → Stop hook (
```
harness-events.py stop
```
) trả exit 2, đưa danh sách lệch về.
Khi bị block: trích nguyên văn
```
[R3 index-sync] wiki/index.md chưa liệt kê: …
```
, rồi thêm đúng 1 row cho tour-demo vào
```
wiki/index.md
```
, sang dọn dẹp.

→ tiếp Dọn dẹp (dưới).

KỊCH BẢN FULL (khi ARGUMENTS có

full

) — R1–R10 tuần tự

Diễn 6 cảnh chặn-live (R1,R2,R3,R5,R7,R9) + 3 cái không-chặn cho xem artifact (R4,R8,R10) + 1 cái repo (R6). Nói rõ trước nhóm không-chặn: "3 rule sau KHÔNG chặn lúc gõ — chúng GHI/NHẮC; tôi sẽ chỉ artifact làm bằng."

R1 — Write
llmwiki/raw/tour-demo.md
→ CHẶN (deny raw/). Trích, không retry.

R2 — Write
llmwiki/wiki/sources/draft/tour-demo.md
(CÓ frontmatter

---\ntype: draft\n---

để R9 qua, nhưng thiếu

## Origin

) → CHẶN → thêm

## Origin

→ PASS.

R3 — (Stop) kết thúc lượt khi file R2 chưa vào

index.md

→ Stop block → thêm row index → tiếp. (Trong FULL, để liền mạch có thể gộp R3 vào cuối: sau khi tạo các file PASS bên dưới, thử kết thúc 1 lượt còn lệch index → block → cập nhật index.)

R4 — log-append (KHÔNG chặn): sau một Write PASS, chỉ

.claude/audit/audit.jsonl

vừa có dòng mới (tool+path+timestamp) và

.claude/audit/log.md

được sinh lại.

cat

vài dòng cuối làm bằng — "máy ghi, tôi không xoá được."

R5 — Write
llmwiki/wiki/tour-demo.md
(ngay dưới

wiki/

) → CHẶN

[R5 folder-structure] …

(file wiki phải nằm trong concepts/entities/…). Không retry.

R6 — verify-before-commit (repo, KHÔNG chặn-live): chỉ ra cổng commit gồm pre-commit hook + CI

.github/workflows/harness.yml

(gọi lõi

files

mode trên .md đổi) + skill

/verify-before-commit

(Claude tự soi code mới trước khi commit). Đây là tầng repo, không phải session — không demo block trực tiếp.

R7 — Write
llmwiki/wiki/sources/draft/tour-demo-proposal.md
có frontmatter +

## Origin

## Plan

proposed

nhưng THIẾU

## Agent Task Assignment

Sequence diagram

→ CHẶN

[R7 proposal-complete] …

→ sửa thêm 2 mục đó → PASS.

R8 — pattern-health (KHÔNG chặn): chạy

python3 harness/poc-vendor-neutral/bin/harness-events.py session

để hiện dòng

[harness] N rule đang gác…

(+ cảnh báo drift nếu policy lệch remote). Đây là thứ in lúc SessionStart.

R9 — Write
llmwiki/wiki/concepts/tour-demo.md
có

## Origin

nhưng KHÔNG có YAML frontmatter → CHẶN

[R9 okf-frontmatter] …

(thiếu

type

) → sửa thêm

---\ntype: concept\n---

lên đầu → PASS.

R10 — docs-gate (KHÔNG chặn):

cat .claude/audit/.docs-gate.json

cho thấy bộ đếm prompt; giải thích mỗi

LLMWIKI_DOCS_GATE_EVERY

(mặc định 5) lượt, UserPromptSubmit chèn directive đề nghị gọi

/docs-site-macos

Kết FULL: bảng 10 rule — cái nào chặn-live, cái nào ghi/nhắc, cái nào ở repo; trích

.claude/audit/*.jsonl

làm bằng.

Dọn dẹp (BẮT BUỘC — cùng một lượt, kẻo R3 chặn)

Xóa MỌI file

tour-demo*

đã PASS (được tạo) và xóa row tương ứng trong

wiki/index.md

trong cùng lượt (xóa file mà để row → index lệch → Stop hook chặn chính lượt dọn):

SHORT:
```
wiki/sources/draft/tour-demo.md
```
+ row của nó.

FULL: thêm

wiki/sources/draft/tour-demo-proposal.md

wiki/concepts/tour-demo.md

+ các row.

Các file bị CHẶN (raw/tour-demo, wiki/tour-demo R5) không tồn tại → khỏi xóa.
Artifact harness (
```
audit.jsonl
```
,
```
log.md
```
,
```
.docs-gate.json
```
) là bản ghi máy hợp lệ → giữ nguyên, không xóa.
TUYỆT ĐỐI không đụng file có sẵn khác của project.

Kết màn: tóm 1 đoạn các rule vừa chặn + "mọi tool call vừa rồi nằm trong

.claude/audit/*.jsonl

— máy ghi, tôi không quên được" (cat vài dòng cuối). Bản máy-diễn không cần phiên:

bash harness/poc-vendor-neutral/demo.sh

(13 assertion) ·

test-broad.sh

(63).

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	user_optional	ARGUMENTS có `full` / `10` / "đầy đủ"	KỊCH BẢN FULL R1–R10 thay SHORT	mặc định → SHORT	W04
B02	conditional_required	pre-check in `PROD`	diễn y hệt, chỉ khác tên hook script ( `pre_tool_use.py` / `post_tool_use.py` / `stop.py` ), R1 có thể chặn qua `permissions.deny`	—	W03
B03	recovery	pre-check không in gì (MISSING)	DỪNG, gợi ý lệnh curl `bootstrap.sh` PoC (khối Pre-check) rồi mở session MỚI tại root project	không diễn	kết thúc
B04	user_optional	user hỏi "sao /mcp không thấy"	giải thích harness là HOOK (kiểm `/hooks` ), không phải MCP	—	W03

Validation và stopping

Mỗi cảnh chặn-live chỉ tính khi hook thật trả exit 2 và stderr được trích nguyên văn; không retry sau chặn (trừ bước khắc phục đã định). Tour dừng ngay khi một rule chặn-live không chặn. Xong khi không còn

tour-demo*

và

wiki/index.md

khớp.

Examples

Positive:
```
/harness-tour
```
trên project đã cài PoC → pre-check in
```
POC
```
→ Write
```
llmwiki/raw/tour-demo.md
```
bị chặn
```
[R1 no-write-raw] …
```
→ R2 chặn rồi PASS sau khi thêm
```
## Origin
```
→ kết lượt bị Stop
```
[R3 index-sync] …
```
→ thêm row → dọn
```
wiki/sources/draft/tour-demo.md
```
+ row cùng lượt.
Boundary/failure:
```
/harness-tour full
```
mở ở repo nguồn (không load
```
.claude/settings.json
```
của project) → pre-check không in gì → MISSING, dừng, gợi ý lệnh curl bootstrap + mở session mới; không diễn cảnh nào.

harness-tour

NPX Install

Tags

SKILL.md Content

Skill: harness-tour

WHAT

Purpose và context

Mental model

Input và output contract

Rules và capabilities

Failure boundaries

HOW

Main workflow

Chọn độ dài tour (đọc ARGUMENTS)

Pre-check — phát hiện harness nào đang sống trong session

Harness là HOOK, KHÔNG phải MCP (giải thích nếu user hỏi "sao /mcp không thấy")

Bảng map path → rule (DÙNG ĐÚNG path để mỗi cảnh chỉ kích 1 rule)

KỊCH BẢN SHORT (mặc định) — 3 cảnh, diễn TUẦN TỰ, tường thuật TRƯỚC mỗi cảnh

KỊCH BẢN FULL (khi ARGUMENTS có
`full`
) — R1–R10 tuần tự

Dọn dẹp (BẮT BUỘC — cùng một lượt, kẻo R3 chặn)

Branches

Validation và stopping

Examples

harness-tour

NPX Install

Tags

SKILL.md Content

Skill: harness-tour

WHAT

Purpose và context

Mental model

Input và output contract

Rules và capabilities

Failure boundaries

HOW

Main workflow

Chọn độ dài tour (đọc ARGUMENTS)

Pre-check — phát hiện harness nào đang sống trong session

Harness là HOOK, KHÔNG phải MCP (giải thích nếu user hỏi "sao /mcp không thấy")

Bảng map path → rule (DÙNG ĐÚNG path để mỗi cảnh chỉ kích 1 rule)

KỊCH BẢN SHORT (mặc định) — 3 cảnh, diễn TUẦN TỰ, tường thuật TRƯỚC mỗi cảnh

KỊCH BẢN FULL (khi ARGUMENTS có full) — R1–R10 tuần tự

Dọn dẹp (BẮT BUỘC — cùng một lượt, kẻo R3 chặn)

Branches

Validation và stopping

Examples

KỊCH BẢN FULL (khi ARGUMENTS có
`full`
) — R1–R10 tuần tự