docs(framework): write the hook contract in docs/ARCHITECTURE.md

Đang mở Phù hợp với người mới
#1,197 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
78/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
documentation

Hướng nghiên cứu

Đọc các quy tắc 5 và 7 trong docs/ARCHITECTURE.md, sau đó tìm tham chiếu 08-hook-generate và hợp đồng hook trước đó trong PR #1158. Thêm phần hợp đồng được yêu cầu và điều chỉnh các quy tắc đó cho phù hợp; bảng tương thích theo từng công cụ nằm ngoài phạm vi. Hoàn tất khi cả ba tiêu chí chấp nhận đều được đáp ứng.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Problem

Hooks the framework ships must behave the same on every supported tool. The contract lives in PR #1158 and in session notes, not in one place a hook author or the hook generator can follow. Two hooks written without it already disagree (#1190).

Scope

Add a short section to docs/ARCHITECTURE.md:

  • A hook is a script: deterministic, no model, no network, 5 s timeout, one purpose.
  • Two reactions: inform (additionalContext) or require (decision: "block" with a reason). Say nothing when there is nothing to report.
  • Shared moments: SessionStart, PostToolUse, Stop. Optional where the tool has them: PreToolUse, UserPromptSubmit, SubagentStop.
  • Rules: judge only what changed this turn (sha1 baseline of the relevant files, not a tool-name filter); report only new findings; require nothing that cannot be done yet; require at most once per turn, tracked in the script; neutral message that says what to do; git read-only; no state outside the script's own baseline file.
  • Scope statement: hooks a user generates for one tool with 08-hook-generate are not bound by this contract.

Per-tool facts go to COMPATIBILITY.md (#978), not here.

Acceptance criteria
  • The section exists in docs/ARCHITECTURE.md.
  • 08-hook-generate references it.
  • Rules 5 and 7 of ARCHITECTURE.md are consistent with it.
Prior art in this repo
  • #1158 (one hook contract), #1146 (git allowed read-only), #1190 (plan check false positives), #978 (verified compatibility).
Out of scope

The per-tool table (#978). Bridge fixes (#1191, #1193, #1194).

Ngôn ngữ chính
TypeScript
Star
481
Fork
45
Merge trung bình
1 ngày 13 giờ
Pull request đã merge (30 ngày)
91

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của ai-driven-dev/framework

Tất cả issue của ai-driven-dev/framework

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.