hs:cook

Execute the plan, leave a trailThực thi plan, để lại dấu vết

TDD red→green

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.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.

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. On a plan carrying defer_suite: true that re-run scopes to the files this phase declares, and the full suite runs once before the plan can close.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. Với plan mang defer_suite: true, lượt chạy lại đó thu về đúng tập file phase này khai, và suite đầy đủ chạy một lần trước khi plan được đóng.

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 advise, then passXem nó nhắc, rồi cho qua

Worked exampleVí dụ thật

Advisory, then pass — the artifact is the keyNhắc, rồi cho qua — artifact là chìa

The end-to-end slice in a temp dir: a push without the artifact gets an advisory (exit 0) naming the gap; cook writes verification.json; the same push with it passes — and every gate event carries an actor. Locally the presence gate only advises; it never blocks you. real e2e Lát end-to-end trong temp dir: push thiếu artifact nhận advisory (exit 0) nêu tên chỗ thiếu; cook ghi verification.json; cùng push đó có artifact thì qua — và mọi gate event mang actor. Tại máy, presence gate chỉ advisory; không bao giờ chặn bạn. e2e thật

python3 harness/e2e/run_vertical_slice.py

e2e vertical slice in /tmp/harness-e2e-63ccm1j6 (simulated transport: stdin JSON subprocess, not native Claude Code)
  ✓ session_init continues
  ✓ session file written with actor
  ✓ push without artifact ADVISORY exit 0
  ✓ advisory names the missing artifact
  ✓ push with artifact PASSES exit 0
  ✓ push ADVISORY on a FAILed check (exit 0)
  ✓ push ADVISORY on a BLOCKED verdict (exit 0)
  ✓ push ADVISORY on an off-enum verdict (exit 0)
  ✓ push ADVISORY on an empty checks array (exit 0)
  ✓ push PASSES again after restoring a valid artifact
  ✓ bugfix missing regression ADVISORY (DoD)
  ✓ bugfix with regression PASSES (DoD)
  ✓ pr ADVISORY with only verification (names missing review-decision)
  ✓ pr ADVISORY with verification+review but no plan-approval
  ✓ pr PASSES with verification + review + a valid plan-approval
  ✓ pr ADVISORY after the plan body changed (approval drift re-opens)
  ✓ disabled gate skips exit 0
  ✓ pre-push hook passes with artifact
  ✓ pre-push hook WARNS without artifact (exit 0)
  ✓ forgery write to a receipt path STILL BLOCKS (exit 2)
  ✓ trace has gate events
  ✓ every gate event carries an actor
  ✓ both advisory and pass were traced
  ✓ skip was traced with reason
  ✓ [global] tool-Write into ${bin} hook BLOCKS (exit 2)
  ✓ [global] whole-bin catch-all BLOCKS a non-guarded bin path (exit 2)
  ✓ [global] legit project .harness/ write PASSES (exit 0)

e2e: 2026-07-14T03:48:22Z | 27 passed, 0 failed | transport=simulated-stdin

27/27 checks. The gate reads the artifact off the filesystem — no commit needed — the gate never asks git what it knows.27/27 check. Gate đọc artifact từ filesystem — không cần commit — gate không bao giờ hỏi git xem nó biết gì.

The per-phase loopVòng lặp từng phase

conformanceconformance

files vs standardsfile vs standards

→

red → greenđỏ → xanh

test-first, paired committest-trước, commit cặp

→

verification.json

machine-writtenmáy-ghi

→

trace

event + actorevent + actor

Trace goes through trace_log.py (append_event — the actor resolves itself; never hand-roll JSONL). Trace is fail-open telemetry, not compliance — the compliance gate runs regardless.Trace đi qua trace_log.py (append_event — actor tự resolve; không tự chế JSONL). Trace là telemetry fail-open, không phải compliance — gate compliance luôn chạy.

Under the hood — `hs-run cook`Bên trong — `hs-run cook`

The skill drives the cook domain of hs-run — the deterministic step-sequence engine — through 8 verbs: open, preflight, next, record, verify, status, close, prompt. Each returns a JSON envelope (state, next_action, artifacts, refs) on one of six exit codes: 0 done, 1 findings, 2 broken, 3 deliberate refusal, 10 needs a model turn, 11 one more deterministic step — only cook and plan have more than one door into the chain; the other 11 domains expose just next.Skill chạy domain cook của hs-run — engine bước chạy tất định — qua 8 verb: open, preflight, next, record, verify, status, close, prompt. Mỗi verb trả envelope JSON (state, next_action, artifacts, refs) trên một trong sáu mã thoát: 0 xong, 1 phát hiện, 2 hỏng, 3 từ chối có chủ đích, 10 cần lượt model, 11 còn một bước tất định — chỉ cook và plan có nhiều hơn một cửa vào chuỗi; 11 domain còn lại chỉ có next.

🟦

Grid plans get a preflight check. When the plan stamped grid: true (from hs:plan --grid), cook re-checks the coverage-grid artifact at its Phase-DAG preflight via grid_emit_guard.py --require — a hard presence gate (exit 2 → STOP) that catches "declared grid but emitted nothing". The verdict itself stays advisory; the coverage artifact then flows to hs:test and code-review. Mechanics: Methodology.Plan grid có một bước kiểm preflight. Khi plan đóng dấu grid: true (từ hs:plan --grid), cook kiểm lại artifact coverage-grid ở Phase-DAG preflight qua grid_emit_guard.py --require — một presence gate cứng (exit 2 → STOP) bắt "khai grid nhưng emit rỗng". Bản thân verdict vẫn advisory; artifact coverage rồi chảy sang hs:test và code-review. Cơ chế: Phương pháp.

🎯

Deferred-suite plans scope each phase, and owe one full run. When the plan stamped defer_suite: true (from hs:plan --defer-suite), each phase runs only the test files its plan-graph node declares — resolved against the tree the plan itself lives in, never the ambient one. The debt comes due at the end: cook close refuses (state suite_debt_unpaid, exit 3) until one run is recorded and stamped as the deferred-suite run. Verdict alone was not enough — every per-phase verify overwrote the same record, so the last phase settled the debt silently. Stated limit: the stamp says which run it was, not how much it ran. A paused phase left once every counted one passes stops the plan too: cook next asks paused_remaining (exit 10) whether to build it or close without it (closes_without: true), and cook close refuses with phases_paused (exit 3) until one is chosen.Plan hoãn suite thu hẹp từng phase, và nợ một lượt chạy đầy đủ. Khi plan đóng dấu defer_suite: true (từ hs:plan --defer-suite), mỗi phase chỉ chạy đúng tập test mà node của nó khai trong plan-graph — phân giải theo cây mà chính plan sống trong đó, không bao giờ theo cây môi trường. Nợ đến hạn ở cuối: cook close từ chối (trạng thái suite_debt_unpaid, exit 3) cho tới khi có một lượt chạy được ghi nhận và đóng dấu đúng là lượt trả nợ. Chỉ verdict thôi thì không đủ — mọi lượt verify per-phase đều ghi đè cùng một bản ghi, nên phase cuối trả nợ hộ trong im lặng. Giới hạn nói thẳng: con dấu nói lượt chạy ĐÓ là lượt nào, không nói nó chạy bao nhiêu. Một phase tạm dừng còn lại khi mọi phase được đếm đã qua cũng chặn plan: cook next hỏi paused_remaining (exit 10) xây nó hay đóng plan không có nó (closes_without: true), và cook close từ chối với phases_paused (exit 3) cho tới khi chọn một trong hai.

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.

HARD-GATE — wiring is real.wiring là thật. gate_stage.py ADVISES locally (exit 0) when verification.json is missing or a review-decision verdict ≠ PASS, naming what to create — it never blocks you. What hard-blocks with no CI required: the path-keyed write floors and the artifact-forgery check. Faking a report (writing PASS while failing) still leaves a trace — actor keeps a record of who wrote what. gate_stage.py NHẮC tại máy (exit 0) khi thiếu verification.json hoặc verdict review-decision ≠ PASS, nêu tên thứ cần tạo — không bao giờ chặn bạn. Cái chặn cứng mà không cần CI: các sàn ghi theo đường-dẫn và check chống-giả-mạo artifact. Báo cáo gian (ghi PASS khi đang fail) vẫn để lại trace — actor 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?

Not through the workflow — with no approved plan it returns you to hs:plan. The require_plan gate itself only advises locally (exit 0) and never hard-blocks on its own; wire the optional receipts-gate CI workflow into your own repo if you want it enforced on every push too.Không qua workflow — khi chưa có plan duyệt, nó đưa bạn về hs:plan. Bản thân gate require_plan chỉ advisory tại máy (exit 0) và không tự chặn cứng; gắn workflow CI receipts-gate (tùy chọn) vào CI của repo bạn nếu muốn ép nó trên mọi push nữa.

Do I have to commit the artifacts for the gate to pass?Có cần commit artifact để gate qua không?

No. The gate reads verification.json off the filesystem, so it clears the moment the file is written — before any commit, and whether or not you ever commit it. (Plan directories themselves are tracked; what stays local is plans/reports/ plus raw runner output — coverage.xml, junit-*.xml.)Không. Gate đọc verification.json từ filesystem, nên nó thông ngay khi file được ghi — trước mọi commit, và bất kể bạn có commit hay không. (Bản thân plan dir có được git track; thứ ở lại cục bộ là plans/reports/ cùng output thô của runner — coverage.xml, junit-*.xml.)

I'm stuck between two comparable approaches mid-phase.Kẹt giữa hai cách ngang nhau giữa phase.

Escalate to 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?

Into 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?

No. 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.

← PrevTrướchs:planhs:plan OverviewTổng quan▦NextSau →hs:tesths:test