[P1] Document hook execution semantics and state transitions #4

New Issue

joe · 2026-03-31T19:58:36-05:00

joe commented

2026-03-31 19:58:36 -05:00

Council finding: the Nu-based hook runner (nothooks) implements phase-awareness and setup-hook state tracking, but this is not documented with concrete examples.

What to document:

HookPhase::Dot vs HookPhase::Setup — when each runs, what triggers re-run
State file format (.nothooks-state.toml) — what is persisted, how it is read
--force flag behavior — which hooks re-run
A concrete end-to-end example: new machine → dot phase → setup phase → state written
Reference the Nu script conventions assumed by the runner

Add to README or a docs/hooks.md.

Source: devloop council analysis 2026-03-31

Council finding: the Nu-based hook runner (`nothooks`) implements phase-awareness and setup-hook state tracking, but this is not documented with concrete examples. **What to document:** - `HookPhase::Dot` vs `HookPhase::Setup` — when each runs, what triggers re-run - State file format (`.nothooks-state.toml`) — what is persisted, how it is read - `--force` flag behavior — which hooks re-run - A concrete end-to-end example: new machine → dot phase → setup phase → state written - Reference the Nu script conventions assumed by the runner Add to README or a `docs/hooks.md`. Source: devloop council analysis 2026-03-31

joe referenced this issue from a commit

2026-04-04 00:14:33 -05:00

fix: address security findings from devkit-review (#1–#7)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: joe/notfiles#4