hs:cook
Takes a human-approved plan and works it phase by phase: red→green TDD, a machine-written verification.json at each phase end, a trace event with an actor for every meaningful step. No approved plan → it sends you back to hs:plan (and the hard gate blocks the shortcut anyway).Nhận một plan đã người duyệt và làm từng phase: TDD đỏ→xanh, một verification.json máy-ghi cuối mỗi phase, một event trace kèm actor cho mọi bước đáng kể. Không có plan duyệt → quay về hs:plan (và hard gate vẫn chặn đường tắt).
When to useKhi nào dùng
✓ Reach for it when✓ Dùng khi
- a plan is approved and you're ready to implementplan đã duyệt và bạn sẵn sàng implement
- you want red→green discipline with paired commitsbạn muốn kỷ luật đỏ→xanh với commit cặp
- every step should be traceable to an actormọi bước nên truy được về một actor
✗ Won't do✗ Sẽ không làm
- run without an approved plan — back to
hs:planchạy khi chưa duyệt plan — quay vềhs:plan - edit gate config to slip past — every edit shows a diffsửa config gate để lách — mọi sửa lộ diff
- auto-ship — push/pr/ship always hit the gatetự ship — push/pr/ship luôn qua gate
How to run itCách chạy
From a clean context, pass the approved plan's absolute path: /hs:cook /abs/path/plans/<id>/plan.md. If plan and cook share a session, the cook_isolation_nudge reminds you to /clear first (advisory — it never blocks).Từ context sạch, truyền đường dẫn tuyệt đối của plan đã duyệt: /hs:cook /abs/path/plans/<id>/plan.md. Nếu plan và cook chung một phiên, cook_isolation_nudge nhắc bạn /clear trước (advisory — không chặn).
Conformance checklistChecklist conformance
Read the phase file, list files to create/modify, match naming/format to standards. Any deviation from the plan → STOP and ask, never silently change.Đọc phase file, liệt kê file tạo/sửa, khớp tên/định dạng với standards. Lệch khỏi plan → DỪNG và hỏi, không tự đổi.
Red → greenĐỏ → xanh
Write the failing test first (intentional red), implement until green, re-run the full suite, then a paired commit of test + module.Viết test fail trước (đỏ có chủ đích), implement đến khi xanh, chạy lại cả suite, rồi commit cặp test + module.
Simplification passLượt rút gọn
On green, if the change grew a special case or duplicated an existing pattern, collapse it — the suite must stay green.Khi xanh, nếu thay đổi sinh case đặc biệt hoặc lặp pattern đã có, gộp lại — suite phải vẫn xanh.
Verify before doneVerify trước khi xong
Suite green, no new lint/type errors, every acceptance criterion has file:line evidence, no silent contract change. A side effect → STOP and ask, don't self-patch.Suite xanh, không lỗi lint/type mới, mọi tiêu chí nghiệm thu có bằng chứng file:line, không đổi contract ngầm. Có side effect → DỪNG và hỏi, không tự vá.
Write artifactsGhi artifact
At phase end write verification.json (+ review-decision.json when a review happened). The gate reads them off the filesystem — no commit needed.Cuối phase ghi verification.json (+ review-decision.json khi có review). Gate đọc từ filesystem — không cần commit.
Trace, then next phaseTrace, rồi phase tiếp
append_event records the actor + step. Whether it pauses for you depends on HARNESS_AUTONOMY.append_event ghi actor + bước. Có dừng hỏi bạn hay không tùy HARNESS_AUTONOMY.
See it block, then passXem nó chặn, rồi cho qua
Block, then pass — the artifact is the keyChặn, rồi cho qua — artifact là chìa
The end-to-end slice in a temp dir: a push without the artifact is blocked at exit 2; cook writes verification.json; the same push with it passes — and every gate event carries an actor. real e2e
Lát end-to-end trong temp dir: push thiếu artifact bị chặn exit 2; cook ghi verification.json; cùng push đó có artifact thì qua — và mọi gate event mang actor. e2e thật
e2e vertical slice in /tmp/harness-e2e-3ehy1mia (simulated transport: stdin JSON subprocess, not native Claude Code) ✓ session_init continues ✓ session file written with actor ✓ push without artifact BLOCKS exit 2 ✓ block reason names the missing artifact ✓ push with artifact PASSES exit 0 ✓ disabled gate skips exit 0 ✓ pre-push hook passes with artifact ✓ pre-push hook blocks without artifact ✓ trace has gate events ✓ every gate event carries an actor ✓ both block and pass were traced ✓ skip was traced with reason e2e: 2026-06-13T15:29:07.109629+00:00 | 12 passed, 0 failed | transport=simulated-stdin
12/12 checks. The gate reads the artifact off the filesystem — no commit needed (and .gitignore keeps new plan dirs out of git, so artifacts can't auto-commit; that's policy, not a bug).12/12 check. Gate đọc artifact từ filesystem — không cần commit (và .gitignore che plan dir mới, nên artifact không tự commit; đó là policy, không phải lỗi).
The per-phase loopVòng lặp từng phase
Trace goes through trace_log.py (append_event — the actor resolves itself; never hand-roll JSONL). A phase declared stateless may skip trace; the compliance gate still runs, because trace is fail-open telemetry, not compliance.Trace đi qua trace_log.py (append_event — actor tự resolve; không tự chế JSONL). Một phase khai stateless có thể bỏ trace; gate compliance vẫn chạy, vì trace là telemetry fail-open, không phải compliance.
The autonomy dial — where it stops to askNúm tự-trị — nó dừng hỏi ở đâu
One env var, HARNESS_AUTONOMY, sets the leash. Default stops at exactly two human checkpoints. god never stops mid-chain — but the trace still records everything. No level auto-ships.Một biến env, HARNESS_AUTONOMY, đặt độ dài dây. Default dừng ở đúng hai chốt người. god không dừng giữa chuỗi — nhưng trace vẫn ghi đủ. Không mức nào tự ship.
gate_stage.py blocks a hard stage when verification.json is missing (exit 2 + the path to create it) or a review-decision verdict ≠ PASS. Faking a report (writing PASS while failing) surfaces the moment CI re-runs the suite, and the trace keeps a record of who wrote what.
gate_stage.py chặn stage cứng khi thiếu verification.json (exit 2 + đường tạo) hoặc verdict review-decision ≠ PASS. Báo cáo gian (ghi PASS khi đang fail) lộ ngay khi CI chạy lại suite, và trace giữ vết ai ghi gì.
FAQHỏi đáp
Can I cook without an approved plan?Cook khi chưa duyệt plan được không?
hs:plan, and the require_plan gate blocks the hard stages anyway — there's no shortcut to ship.Không. Khi chưa có plan duyệt, nó đưa bạn về hs:plan, và gate require_plan vẫn chặn các stage cứng — không có đường tắt để ship.Do I have to commit the artifacts for the gate to pass?Có cần commit artifact để gate qua không?
verification.json off the filesystem. .gitignore deliberately keeps new plan dirs out of git, so artifacts don't auto-commit — correct policy, not a bug.Không. Gate đọc verification.json từ filesystem. .gitignore cố ý che plan dir mới khỏi git, nên artifact không tự commit — đúng policy, không phải lỗi.I'm stuck between two comparable approaches mid-phase.Kẹt giữa hai cách ngang nhau giữa phase.
hs:bakeoff: probe the alternatives and decide by numbers, then resume cook — instead of grinding one direction on a hunch.Chuyển sang hs:bakeoff: thử các phương án và quyết bằng số, rồi quay lại cook — thay vì cắm cúi một hướng theo cảm tính.Where does work that's outside the plan go?Việc ngoài phạm vi plan thì để đâu?
BACKLOG.md. Don't steer the plan mid-flight — capture it and keep the current phase honest.Vào BACKLOG.md. Đừng đổi hướng plan giữa chừng — ghi lại và giữ phase hiện tại trung thực.Does HARNESS_AUTONOMY=god let it ship on its own?HARNESS_AUTONOMY=god có tự ship không?
god only stops the mid-chain pauses — the trace still records every step, and no level self-ships: push|pr|ship|deploy always passes the artifact gate.Không. god chỉ bỏ các lần dừng giữa chuỗi — trace vẫn ghi đủ mọi bước, và không mức nào tự ship: push|pr|ship|deploy luôn qua artifact gate.