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

Abierto Apto para principiantes
#1,197 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
78/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript

Línea de trabajo

Lee las reglas 5 y 7 de docs/ARCHITECTURE.md y luego busca la referencia a 08-hook-generate y el contrato anterior del hook en PR #1158. Añade la sección del contrato solicitada y ajusta esas reglas a ella; la tabla de compatibilidad por herramienta queda fuera del alcance. El trabajo estará terminado cuando se cumplan los tres criterios de aceptación.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
TypeScript
Estrellas
481
Forks
45
Merge medio
1 d 13 h
PR fusionados (30 d)
91

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ai-driven-dev/framework

Todos los issues de ai-driven-dev/framework

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.