The rig
Behind the 68 skills sits the enforcement layer: 66 registered hooks in three tiers, a multi-agent coordination layer (claims · plan-approval · write-guard), and read-only telemetry that ends every report with what it cannot measure. It reports whether the machinery runs — never whether the product wins the market.Sau 68 skill là lớp cưỡng chế: 66 hook đã đăng ký chia ba hạng, một lớp phối hợp đa-agent (claims · plan-approval · write-guard), và telemetry chỉ-đọc kết mỗi báo cáo bằng cái nó không đo được. Nó báo máy móc có chạy không — không bao giờ báo sản phẩm có thắng thị trường không.
What it can and can't tell youNó nói được gì và không nói được gì
✓ It can tell you✓ Nó nói được
- which skills actually ran, and in what chainskill nào thực sự chạy, theo chuỗi nào
- whether a hard stage was blocked, and who actedstage cứng có bị chặn không, ai đã thao tác
- declared vs actual workflow deviationslệch chuỗi khai-báo vs thực-tế
✗ It can't tell you✗ Nó không nói được
- market / user outcome — usage ≠ effectivenesskết quả thị trường / người dùng — mức dùng ≠ hiệu quả
- exact token / dollar cost — not attributedtoken / $ chính xác — không quy được
- semantic correctness — only ran / coarse exitđúng-sai ngữ nghĩa — chỉ ran / exit thô
Inspect the rig yourselfTự kiểm bộ máy
Everything is on the filesystem — no dashboard, no server. These commands read what the harness recorded.Mọi thứ nằm trên filesystem — không dashboard, không server. Các lệnh này đọc cái harness đã ghi.
See what actually ranXem cái thực sự chạy
python3 harness/scripts/analyze_telemetry.py --lens all — the workflow lens compares declared vs actual; the mandatory ## NOT measured block keeps a partial read from looking complete.python3 harness/scripts/analyze_telemetry.py --lens all — workflow lens so khai-báo vs thực-tế; khối bắt buộc ## NOT measured chặn việc đọc một phần trông như đủ.
Read the audit trailĐọc sổ audit
Open state/trace/trace-YYYYMMDD.jsonl — append-only gate / approval / DEC events, each with an actor + ts. It never rotates.Mở state/trace/trace-YYYYMMDD.jsonl — sự kiện gate / approval / DEC append-only, mỗi cái có actor + ts. Không xoay vòng.
Verify integrityKiểm toàn vẹn
python3 harness/scripts/verify_install.py --strict hashes every tracked file and checks the registered hooks match. Tamper with one and it fails.python3 harness/scripts/verify_install.py --strict hash mọi file tracked và kiểm hook đã đăng ký khớp. Sửa một cái là fail.
Toggle or silenceBật/tắt hoặc làm im
Flip a hook in harness/data/harness-hooks.yaml (git-tracked — the diff shows). Silence all observation with HARNESS_TELEMETRY_DISABLED=1.Bật/tắt một hook trong harness/data/harness-hooks.yaml (tracked git — lộ diff). Tắt mọi quan sát bằng HARNESS_TELEMETRY_DISABLED=1.
Worked example: declared vs actualVí dụ thật: khai-báo vs thực-tế
The workflow lens — declared vs actualWorkflow lens — khai-báo vs thực-tế
Same data, two renders: md to read (note the ## NOT measured honesty block) and json to pipe. The registry ships 12 lenses today, all present; a lens whose module were missing is named "absent", not hidden. real output
Cùng dữ liệu, hai kiểu render: md để đọc (để ý khối trung thực ## NOT measured) và json để nối ống. Registry hôm nay ship 12 lens, tất cả đều có; lens nào thiếu module thì gắn tên "absent", không giấu. đầu ra thật
# Telemetry ## lens: workflow_chains _sessions analyzed: 62 · sufficient: True · gated: False_ | chain | count | | -------------------------- | ----: | | cook | 10 | | plan | 8 | | prompt | 5 | | discover | 4 | | plan → sequential-thinking | 4 | | code-review | 2 | | claude-api | 2 | | release → discover | 2 | | code-review → code-review | 2 | | prompt → prompt | 2 |
{
"lens": "workflow_chains",
"days": 30,
"sessions_analyzed": 62,
"sufficient": true,
"min_sessions": 5,
"common_chains": [
{
"chain": "cook",
"count": 10
},
{
"chain": "plan",
"count": 8
},
{
"chain": "prompt",
"count": 5
},
{
"chain": "discover",
"count": 4
},
{
"chain": "plan → sequential-thinking",
"count": 4
}
],
"common_chains_omitted_for_display": 5
}
No chart library is vendored — the page stays dependency-free. The ## NOT measured section is mandatory: it stops a partial read from looking like full coverage.Không nhúng thư viện vẽ nào — trang giữ không-phụ-thuộc. Mục ## NOT measured là bắt buộc: nó chặn việc đọc một phần trông như đo đủ.
Three hook tiers — the class is carved in codeBa hạng hook — hạng khắc trong code
Config (harness-hooks.yaml, tracked in git) can flip a hook on/off and change its mode — but it can never change a hook's tier. The fail posture follows the tier. Since v6.2.0 that config is two layers: the shipped registry, plus a per-project overlay at <data-root>/harness-hooks.yaml that MERGES over it, so a project can turn one nudge on without editing the file every other project reads. hs-cli hooks reports each hook's resolved posture and which layer decided it; --off/--on <csv> writes only the project layer.Config (harness-hooks.yaml, tracked git) bật/tắt và đổi mode một hook — nhưng không bao giờ đổi được hạng. Tư thế-khi-lỗi theo hạng. Từ v6.2.0 config đó là hai tầng: sổ đã ship, cộng một tầng phủ per-project ở <data-root>/harness-hooks.yaml GỘP lên trên, nên một dự án bật được một nudge mà không phải sửa file mọi dự án khác cùng đọc. hs-cli hooks báo tư thế đã giải của từng hook và tầng nào quyết; --off/--on <csv> chỉ ghi tầng dự án.
Six launchers, one envelopeSáu launcher, một envelope
harness/bin/ holds 171 commands over one shared core, across hs-run (the step engine), hs-cli (the config door), hs-code (the code map), hs-rops (remote runs), hs-secrets and hs-usage. Every exit, a crash or a refusal included, is one JSON line on stdout (hs-envelope/1); --text prints for a person instead. See the cheatsheet for the verbs.harness/bin/ chứa 171 lệnh trên một lõi chung, chia cho hs-run (engine bước), hs-cli (cửa cấu hình), hs-code (bản đồ code), hs-rops (chạy trên máy xa), hs-secrets và hs-usage. Mọi lối ra, kể cả crash hay từ chối, là một dòng JSON trên stdout (hs-envelope/1); --text in cho người đọc thay vào đó. Xem verb ở cheatsheet.
Multi-agent coordination (W2)Phối hợp đa-agent (W2)
Several agents/devs work in parallel without stepping on each other — and the presence gate gets harder to cheat cheaply.Nhiều agent/dev làm song song mà không dẫm chân nhau — và presence gate khó gian rẻ hơn.
A claim has a 4-hour lease and self-reclaims if its owner hangs — atomicity from a spike, never unlink+recreate:Một claim có lease 4 giờ và tự reclaim nếu chủ treo — atomicity từ spike, không bao giờ unlink+tạo lại:
claims — atomic primitivesclaims — nguyên thủy atomic
Race-free by construction, not by locking: acquire is open(O_CREAT|O_EXCL) — exactly one winner. Reclaim renames the claim to a per-reclaimer-unique name — the source dentry is consumed atomically, so every later rename on a stale claim gets ENOENT. Delete-then-recreate is forbidden (proven split-brain in 50-way / 20-way races on ext4 + tmpfs). No heartbeat — renewing a claim is release + acquire, a fresh claim_id.Race-free bằng cấu trúc, không phải bằng lock: acquire là open(O_CREAT|O_EXCL) — đúng một người thắng. Reclaim rename claim sang tên riêng-cho-mỗi-reclaimer — dentry nguồn bị tiêu thụ atomic, nên mọi rename sau trên claim cũ nhận ENOENT. Xóa-rồi-tạo-lại bị cấm (đã chứng minh split-brain qua race 50-chiều / 20-chiều trên ext4 + tmpfs). Không heartbeat — renew claim là release + acquire, claim_id mới.
plan-approval & write-guardplan-approval & write-guard
Plan approval gates pr/ship/deploy on remote CI: a plan_hash must match the normalized plan dir (ignores frontmatter + the auto-updated ## Phases section). Write-guard blocks edits to gate config (a GUARD_LIST constant) locally and a pre-push step scrubs every HARNESS_* var — tamper-evident, not tamper-proof.Plan approval gác pr/ship/deploy trên CI remote: plan_hash phải khớp plan dir chuẩn-hóa (bỏ qua frontmatter + section ## Phases tự cập nhật). Write-guard chặn sửa config gate (hằng GUARD_LIST) local và một bước pre-push scrub mọi biến HARNESS_* — tamper-evident, không tamper-proof.
Two books, two lawsHai sổ, hai luật
Every record setdefaults an actor + ts. The lens registry ships 12 lenses, all present today; any whose module went missing would be named "absent" so the gap stays visible, never silently dropped:Mọi record setdefault một actor + ts. Registry lens ship 12 lens, hôm nay đủ cả; cái nào mất module sẽ bị gắn "absent" để lỗ hổng nhìn thấy được, không bao giờ drop âm thầm:
- token / dollar cost per skill or session — not attributedtoken / $ mỗi skill hay phiên — không quy được
- semantic correctness or quality — only ran / coarse exitđúng-sai hay chất lượng — chỉ ran / exit thô
- human review depth or plan-approval qualityđộ sâu review của người hay chất lượng plan-approval
Prove the tree is intactChứng minh cây còn nguyên
The manifest hashes every git-tracked harness file; --strict also checks that registered hooks match. Tamper with a tracked file and this fails. real outputManifest hash mọi file harness tracked git; --strict còn kiểm hook đã đăng ký khớp. Sửa một file tracked là cái này fail. đầu ra thật
WARN harness/bin/hs-cli: not reachable on PATH — skill bodies tell the user to type `hs-cli`. Fix: `ln -s <repo>/harness/bin/hs-cli ~/.local/bin/hs-cli` (or `install.py --cli` for every launcher; Windows: add <repo>/harness/bin to PATH) … 5 more of the same shape (hs-run, hs-code, hs-rops, hs-secrets, hs-usage: a launcher not yet linked onto PATH) WARN harness/data/harness-hooks.yaml: bash_write_guard: enabled=false in the SSOT but its entrypoint is still wired in .claude/settings.json — not a bug (the process spawns and self-no-ops each matching event under the wire-then-toggle pattern), but it costs a spawn; unwire it there too if you want zero per-event cost … 9 more of the same shape (a hook disabled in the SSOT whose entrypoint stays wired) WARN harness/data/harness-hooks.yaml: hash mismatch (deployer-localized config — expected to differ from the shipped baseline) verify_install OK: manifest + hook registration consistent
state/ is always gitignored and never enters git. Global kill-switch for all observation: HARNESS_TELEMETRY_DISABLED=1. Delete harness/ and it's gone.Offline & tự chứa. Harness không gọi mạng ở đường gate; state/ luôn gitignored và không bao giờ vào git. Công tắc tổng cho mọi quan sát: HARNESS_TELEMETRY_DISABLED=1. Xóa harness/ là hết.FAQHỏi đáp
Can config just disable the compliance gate?Config có thể tắt béng compliance gate không?
harness-hooks.yaml, git-tracked) can toggle a hook on/off and change its mode, but never its tier. The fail posture follows the tier, so compliance stays fail-closed — and any edit shows in the diff.Config (harness-hooks.yaml, tracked git) bật/tắt và đổi mode một hook, nhưng không bao giờ đổi hạng. Tư thế-khi-lỗi theo hạng, nên compliance vẫn fail-closed — và mọi sửa lộ diff.Trace vs telemetry — what's the difference?Trace vs telemetry — khác gì?
setdefault an actor + ts on every record.Trace là sổ audit (sự kiện gate / approval / DEC), không xoay vòng. Telemetry là sổ usage (count / shape / outcome), xoay ở 8MB. Cả hai setdefault actor + ts mỗi record.Does the harness phone home?Harness có "gọi về nhà" không?
state/ is gitignored. Turn off all observation with HARNESS_TELEMETRY_DISABLED=1.Không. Không có network call ở đường gate (invariant grep chứng minh), và state/ gitignored. Tắt mọi quan sát bằng HARNESS_TELEMETRY_DISABLED=1.What can telemetry not tell me?Telemetry không nói được gì?
## NOT measured block names these in every report.Token/$ (không quy được), đúng-sai ngữ nghĩa (chỉ ran / exit thô), độ sâu review của người, và kết quả thị trường/người dùng. Khối ## NOT measured nêu rõ chúng trong mọi báo cáo.How do I remove the harness?Gỡ harness thế nào?
harness/ directory. It's self-contained — a CI invariant forbids the string .claude/skills/ inside harness/.Xoá thư mục harness/. Nó tự chứa — một invariant CI cấm chuỗi .claude/skills/ trong harness/.