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 task from the task-store. 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) lấy task từ task-store. 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.
task_store.py + claims.py write a JSONL record with actor + ts to state/trace/. The append is atomic (single os.write). The trace never rotates — every acquire, reclaim, and release stays in the audit log.
task_store.py + claims.py ghi record JSONL với actor + ts vào state/trace/. Append atomic (một os.write). 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 + SubagentStop hooks fire for each chained subagent, appending event: skill_run records to the telemetry sink (fail-open). The /clear nudge is advisory — it fires on PreToolUse:Read, emits on stderr, never blocks.
Hook SubagentStart + SubagentStop kích hoạt cho mỗi subagent, append record event: skill_run vào telemetry sink (fail-open). Nudge /clear là advisory — kích hoạt trên PreToolUse:Read, 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 four chained subagents: research, constraint-scan, phase-design, and red-team — then validates the result. The output is a machine-readable plan file under plans/.hs:plan chạy bốn subagent nối: research, constraint-scan, thiết kế phase, và red-team — 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/260612-1237-harness-w2-horizontal-1/ artifacts/verification.json phase-01-claims-fsm-team-config.md phase-02-task-store-adapter-github.md phase-03-plan-approval-role-check.md phase-04-write-guard-env-scrub-en-3.md phase-05-memory-gap-staged-port.md phase-06-telemetry-hooks-workflow-lens.md plan.md reports/code-review-260613-phase6-telemetry.md reports/from-code-reviewer-to-planner-red-team-maintainer-operator-plan-review-report.md reports/from-code-reviewer-to-planner-red-team-security-failure-plan-review-report.md
plan_approval.py writes an artifact-plan-approval JSON to plans/<id>/ when approved. The compliance hook gate_stage reads this file at cook/ship time — no file = blocked.
plan_approval.py ghi JSON artifact-plan-approval vào plans/<id>/ khi được duyệt. Hook compliance gate_stage đọc file này tại cook/ship — không có file = bị chặn.
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.
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 one phase_complete event per phase, append-only.
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 phase_complete mỗi phase, 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 blocks ship.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 chặn ship.
{
"stage": "push",
"plan": "260612-1237-harness-w2-horizontal-1",
"actor": "user:dev@team.example",
"ts": "2026-06-12T05:48:36.669571+00:00",
"checks": [
{
"name": "preflight_deps",
"status": "PASS",
"detail": "pytest, pyyaml"
},
{
"name": "pytest harness/tests",
"status": "PASS",
"detail": "258 passed (incl. 5 invariants)"
},
{
"name": "schema load yaml+json",
"status": "PASS",
"detail": "yaml ok, schemas ok"
},
{
"name": "verify_install --strict",
"status": "PASS",
"detail": "manifest 53 files"
},
{
"name": "e2e vertical slice",
"status": "PASS",
"detail": "12 passed, 0 failed, transport=simulated-stdin"
}
],
"verdict": "PASS"
}
Stage gate — compliance hook blocks pushStage gate — hook compliance chặn push
When you run git push or hs:ship, the gate_stage compliance hook fires. It checks the filesystem for the required acceptance artifacts. No artifact? exit 2 with an actionable message. The pre-push git hook is a transport-level backstop.Khi bạn chạy git push hoặc hs:ship, hook compliance 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? exit 2 với thông báo xử lý được. Hook git pre-push là backstop ở tầng transport.
[gate_stage] BLOCKED: 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) [exit 2 — compliance hook fail-closed]
- 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ì?
gate_stage are fail-closed — a missing artifact stops the stage with exit 2.Sink telemetry fail-open — quan sát và không bao giờ chặn. Hook compliance như gate_stage fail-closed — thiếu artifact là dừng stage với exit 2.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.