JourneyHành trình
Follow a single task as the harness carries it through the pipeline — showing what fires, what gets written, and where the gate says no. Each step names the hook or script behind it and the honest limit of the check.Theo một task khi harness đưa qua pipeline — hiển thị cái gì kích hoạt, cái gì được ghi, và nơi gate nói không. Mỗi bước nêu tên hook hoặc script đứng sau và giới hạn trung thực của kiểm tra.
Pick up work — 4-hour claim with auto-reclaimNhận việc — claim 4 giờ, tự reclaim
A developer (or agent) acquires a local claim on the task. The claim has a 4-hour lease — if the owner hangs, any peer can reclaim it safely. Atomicity from a rename, never a delete-and-create.Developer (hoặc agent) acquire một claim local trên task. Claim có lease 4 giờ — nếu chủ treo, bất kỳ peer nào cũng reclaim được an toàn. Atomicity từ rename, không bao giờ xóa-rồi-tạo.
claims.py writes a JSONL record with actor + ts to state/trace/. The append runs under an exclusive flock, best-effort — it never blocks the traced op. The trace never rotates — every acquire, reclaim, and release stays in the audit log.
claims.py ghi record JSONL với actor + ts vào state/trace/. Append chạy dưới flock độc quyền, best-effort — không bao giờ chặn thao tác được trace. Trace không xoay vòng — mọi acquire, reclaim, release đều ở log audit.
hs:discover — shape the ask into a briefhs:discover — định hình yêu cầu thành brief
An ambiguous task enters hs:discover. It chains a research subagent and a brainstorm subagent, then synthesizes a discovery brief — a structured input for planning. A /clear nudge isolates the context before planning begins so the plan skill starts with a clean slate.Task mơ hồ đi vào hs:discover. Nó nối một subagent research và một subagent brainstorm, rồi tổng hợp thành discovery brief — đầu vào có cấu trúc cho planning. Một nudge /clear cô lập context trước khi planning để skill plan bắt đầu với slate sạch.
SubagentStart hook injects the rule and standards context a subagent inherits none of; SubagentStop then appends an outcome record (agent_type, outcome, session) to subagent-outcomes.jsonl (fail-open). The /clear nudge is advisory — it fires on PreToolUse:Skill, emits on stderr, never blocks.
Hook SubagentStart tiêm phần context luật + standards mà subagent không thừa kế; rồi SubagentStop append record outcome (agent_type, outcome, session) vào subagent-outcomes.jsonl (fail-open). Nudge /clear là advisory — kích hoạt trên PreToolUse:Skill, emit ra stderr, không bao giờ chặn.
hs:plan — research · constraint-scan · red-team · validatehs:plan — research · constraint-scan · red-team · validate
hs:plan runs three chained subagent roles — researcher, planner (constraint-scan + phase design), red-teamer — then validates the result. The output is a machine-readable plan file under plans/.hs:plan chạy ba vai subagent nối — researcher, planner (constraint-scan + thiết kế phase), red-teamer — rồi validate kết quả. Đầu ra là file plan đọc được bởi máy dưới plans/.
Plan-approval gateGate duyệt plan
A human approver must sign off explicitly — the approval is not tied to a specific person or role, but the signer is recorded in the artifact. Approval is bound to a normalized plan_hash (frontmatter + auto-updated ## Phases stripped) so reformatting doesn't need re-approval but a content change does.Một người phải ký phê duyệt rõ ràng — phê duyệt không gắn với người hoặc vai trò cụ thể, nhưng người ký được ghi trong artifact. Approval gắn với plan_hash chuẩn hóa (bỏ frontmatter + section ## Phases tự cập nhật) nên reformat không cần duyệt lại nhưng đổi nội dung thì cần.
Plan tree artifactArtifact plan tree
The plan directory structure is captured as a machine-readable artifact. hs:cook reads this to know which phases to execute in order.Cấu trúc thư mục plan được lưu làm artifact đọc được bởi máy. hs:cook đọc đây để biết phase nào thực thi theo thứ tự nào.
plans/260818-0400-rate-limit-middleware/ plan.md phases/phase-1-4.md artifacts/verification.json artifacts/verification-p1.json artifacts/phase-latest-P1.json artifacts/plan-approval.yaml reports/code-review-260818-p1.md
plan_approval.py writes the plan-approval artifact (YAML) to plans/<id>/artifacts/ when approved. The compliance hook gate_stage reads this file at cook/ship time — no file → a local advisory (exit 0) that names the gap; it never blocks you. What stays hard with no CI required: the agent cage, the safety floors, and the artifact-forgery block.
plan_approval.py ghi artifact plan-approval (YAML) vào plans/<id>/artifacts/ khi được duyệt. Hook compliance gate_stage đọc file này tại cook/ship — không có file → advisory tại máy (exit 0) nêu tên chỗ thiếu; không bao giờ chặn bạn. Cái vẫn cứng, không cần CI: cũi agent, các safety floor, và chặn giả-mạo artifact.
hs:cook — TDD red→green, phase by phasehs:cook — TDD đỏ→xanh, từng phase
Each plan phase runs as a TDD cycle: write a failing test first (red), implement until green, emit a phase verification artifact and a trace event. A human checkpoint fires between phases if HARNESS_AUTONOMY=ask_all.Mỗi phase của plan chạy theo chu kỳ TDD: viết test fail trước (đỏ), implement cho đến khi xanh, emit artifact verification của phase và sự kiện trace. Checkpoint người dùng kích hoạt giữa các phase nếu HARNESS_AUTONOMY=ask_all.
hs-run cook <verb> (open, preflight, next, record, verify, status, close, prompt) — each call returns a JSON envelope and one of six exit codes (0 done · 1 findings · 2 broken · 3 deliberate refusal · 10 needs a model turn · 11 one more step). Every Bash tool call runs through PreToolUse:Bash telemetry. Each phase writes plans/<id>/verification.json — the schema is validated by artifact_check.py. The trace log gets an event per significant step (via trace_log.py), append-only.
Vòng lặp phase được chạy bởi hs-run cook <verb> (open, preflight, next, record, verify, status, close, prompt) — mỗi lệnh trả envelope JSON và 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). Mọi lệnh Bash đi qua telemetry PreToolUse:Bash. Mỗi phase ghi plans/<id>/verification.json — schema được validate bởi artifact_check.py. Log trace nhận một sự kiện cho mỗi bước đáng kể (qua trace_log.py), append-only.
hs:test — unit / integration → verification.jsonhs:test — unit / integration → verification.json
hs:test runs the test suite with a unit or integration profile, aggregates the results, and writes a verification.json artifact with a final "verdict": "PASS" or "FAIL". The gate reads this file — a missing or FAIL verdict draws a local advisory (exit 0) and is blocked at the remote CI receipts-gate.hs:test chạy bộ test với profile unit hoặc integration, tổng hợp kết quả, và ghi artifact verification.json với "verdict": "PASS" hoặc "FAIL" cuối cùng. Gate đọc file này — verdict thiếu hoặc FAIL cho advisory tại máy (exit 0) và bị chặn ở receipts-gate CI từ xa.
{
"stage": "push",
"plan": "260818-0400-rate-limit-middleware",
"phase": "p1",
"actor": "user:dev@team.example",
"ts": "2026-08-18T04:12:41.118203+00:00",
"checks": [
{
"name": "preflight_deps",
"status": "PASS",
"detail": "22 declared deps resolved"
},
{
"name": "pytest harness/tests",
"status": "PASS",
"detail": "22405 passed, 418 skipped"
},
{
"name": "schema load yaml+json",
"status": "PASS",
"detail": "yaml ok, schemas ok"
},
{
"name": "verify_install --strict",
"status": "PASS",
"detail": "manifest 3490 files"
},
{
"name": "e2e vertical slice",
"status": "PASS",
"detail": "advisory-then-pass, transport=simulated-stdin"
}
],
"verdict": "PASS"
}
Stage gate — the hook advises on pushStage gate — hook nhắc khi push
When you run git push or hs:ship, the gate_stage hook fires. It checks the filesystem for the required acceptance artifacts. No artifact? An advisory (exit 0) names it and never blocks you; the git pre-push hook is a transport-layer backstop. What does hard-block, no CI required: the agent cage, the safety floors, and the artifact-forgery check.Khi bạn chạy git push hoặc hs:ship, hook gate_stage kích hoạt. Nó kiểm filesystem xem có artifact nghiệm thu cần thiết không. Không có artifact? Một advisory (exit 0) nêu tên nó và không chặn bạn; hook git pre-push là backstop ở tầng transport. Cái chặn cứng, không cần CI: cũi agent, các safety floor, và kiểm giả-mạo artifact.
[advisory] gate_stage: hard stage 'push' needs an active plan but none resolved. Three exits: (1) create a plan under plans/ with `status: in_progress` frontmatter; (2) set HARNESS_ACTIVE_PLAN to the plan dir; (3) set `require_plan: false` for this stage in harness/data/stage-policy.yaml (tracked in git) — presence enforcement lives in remote CI (receipts-gate) [exit 0 — local gate is advisory; the remote CI receipts-gate is the hard block]
- This is a presence gate, not an authentication gate. It checks that the artifact file exists and parses — it cannot prove the content is correct or that the human review was thorough.Đây là presence gate, không phải authentication gate. Nó kiểm file artifact có tồn tại và parse được — không thể chứng minh nội dung đúng hay review người thật sự kỹ lưỡng.
actoris attribution, not identity — a motivated developer can write any string there. It raises the cost of lying; it does not prevent it.actorlà attribution, không phải identity — developer chủ tâm có thể ghi bất kỳ chuỗi nào. Nó tăng giá nói dối; không ngăn được.
Ship — gated pipeline: review → verify → approve → push/prShip — pipeline có gate: review → verify → duyệt → push/pr
hs:ship runs a gated sequence: code-review passes → verification artifact present → a human approves the plan → push or PR is created. Every stage is a gate; any FAIL sends you back to the appropriate repair step.hs:ship chạy chuỗi có gate: review code pass → artifact verification có mặt → người duyệt plan → tạo push hoặc PR. Mỗi stage là gate; bất kỳ FAIL nào đưa bạn về bước sửa phù hợp.
state/trace/trace-YYYYMMDD.jsonl — actor, ts, stage, verdict. The trace never rotates. The workflow lens in analyze_telemetry.py can compare the declared ship chain against the events that actually fired.
Mỗi sự kiện gate ghi record append-only vào state/trace/trace-YYYYMMDD.jsonl — actor, ts, stage, verdict. Trace không xoay vòng. Workflow lens trong analyze_telemetry.py có thể so sánh chuỗi ship khai báo với sự kiện thực sự kích hoạt.
FAQHỏi đáp
Which steps actually require a human?Bước nào thật sự cần người?
default autonomy). Everything between can run automatically — and is still traced. ask_all adds a pause after every phase; god removes the mid-chain pauses.Hai: duyệt plan và ship (ở mức default). Phần ở giữa có thể tự chạy — và vẫn được trace. ask_all thêm dừng sau mỗi phase; god bỏ các lần dừng giữa chuỗi.What's a "presence gate", and what can't it do?"presence gate" là gì, và không làm được gì?
actor is attribution, not identity — it raises the cost of lying, it doesn't prevent it.Nó kiểm artifact cần thiết có tồn tại và parse được. Không chứng minh nội dung đúng hay review người kỹ lưỡng. actor là attribution, không phải danh tính — tăng giá nói dối, không ngăn được.Why does a task claim expire after 4 hours?Vì sao claim task hết hạn sau 4 giờ?
Telemetry hooks vs compliance hooks — what's the difference?Hook telemetry vs compliance — khác gì?
exit 2; the stage-presence gate gate_stage is advisory locally (exit 0 naming the gap) and never blocks you.Sink telemetry fail-open — quan sát và không bao giờ chặn. Vi phạm compliance cứng (giả mạo, secret, nhánh bảo vệ) fail-closed với exit 2; stage-presence gate gate_stage là advisory tại máy (exit 0 nêu tên chỗ thiếu) và không bao giờ chặn bạn.Can I see what actually ran vs what I declared?Xem được cái thực chạy vs cái tôi khai báo không?
state/trace/trace-YYYYMMDD.jsonl (it never rotates), and the workflow lens in analyze_telemetry.py compares the declared chain against the events that actually fired.Có. Mọi sự kiện gate append vào state/trace/trace-YYYYMMDD.jsonl (không xoay vòng), và workflow lens trong analyze_telemetry.py so chuỗi khai báo với sự kiện thực sự xảy ra.