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

未关闭 适合新手
#1,197 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
78/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
typescript
领域
documentation

调研方向

阅读 docs/ARCHITECTURE.md 中的规则 5 和 7,然后查找 08-hook-generate 的引用以及 PR #1158 中之前的 hook 契约。添加所要求的契约章节,并使这些规则与之保持一致;各工具的兼容性表不在范围内。满足全部三项验收标准后即告完成。

由索引模型根据 Issue 内容生成。

描述

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

主要语言
TypeScript
星标
481
派生
45
平均合并
1 天 13 小时
30 天内合并 PR
91

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

ai-driven-dev/framework 的其他 Issue

查看 ai-driven-dev/framework 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。