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

Aperta Adatta ai principianti
#1,197 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
documentation

Direzione di ricerca

Leggi le regole 5 e 7 in docs/ARCHITECTURE.md, poi trova il riferimento a 08-hook-generate e il contratto precedente dell’hook nella PR #1158. Aggiungi la sezione del contratto richiesta e allinea a essa quelle regole; la tabella di compatibilità per strumento è fuori ambito. Il lavoro è completato quando sono soddisfatti tutti e tre i criteri di accettazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
TypeScript
Stelle
481
Fork
45
Merge medio
1g 13h
PR unite (30g)
91

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ai-driven-dev/framework

Tutte le issue di ai-driven-dev/framework

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.