Parfii-bot 249733c164 feat(v0.17.1): orchestrator-dirty-check hook — prevent uncommitted-output compounding

PreToolUse:Agent advisory — warns orchestrator if git status is dirty
before spawning next agent. Closes the workflow gap that caused 28
uncommitted files across 5 bundles on main (2026-04-22 incident).

hooks/orchestrator-dirty-check.sh (51 LOC, POSIX sh):
  - Sources _lib/gate.sh, respects KEI_DISABLED_HOOKS
  - Reads git status --porcelain at repo root
  - Emits stderr advisory with modified/untracked counts + sample
  - Exit 0 always (advisory, not blocking)
  - Bypass: ORCHESTRATOR_META=1 (existing RULE 0.13 flag) or
    ORCHESTRATOR_DIRTY_OK=1 (new, explicit)
  - Severity: warn — per RULE 0.10 ladder; upgrade to enforce
    only after 2nd recurrence

hooks/_lib/test-orchestrator-dirty-check.sh (60 LOC):
  - 5 test cases with mocked git PATH shim
  - Clean / dirty-modified / dirty-untracked / env-bypass /
    gate-bypass
  - PASS 5/5 (existing gate.sh tests unchanged — 11/11)

Wired into hooks/hooks.json (plugin format) and settings-snippet.json
(classic install) at PreToolUse/Agent matcher.

skills/hooks-control/SKILL.md — hook list 9 → 10.
README.md — hook table gains 1 row; count marker left at 9 for
scripts/regen-counts.sh to update post-merge.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 15:42:11 +08:00

4.6 KiB

Raw Blame History

name	description	argument-hint
hooks-control	Runtime enable/disable of KeiSeiKit hooks via env vars (v0.15.1). Click-only wizard that emits shell `export` / `unset` commands for the user to paste. Supports per-hook disable, profile switch (full / advisory-off / minimal / off), or full re-enable. Does NOT execute anything — user controls their shell.	(none — fully click-driven)

Hooks Control — Runtime Hook Enable/Disable

Click-only wizard. Helps you toggle KeiSeiKit hooks for the current shell session via env vars, without editing ~/.claude/settings.json. The skill emits shell commands; it NEVER runs them.

Two env vars are honoured by every kit-shipped hook (v0.15.1+):

Var	Meaning
`KEI_DISABLED_HOOKS`	Comma- or space-list of hook base names (no `.sh`). Matching is tokenized exact-match (v0.15.1 fix — earlier versions used substring-glob, which let `foo-all-bar` disable every hook). The literal `all` token still disables every hook.
`KEI_HOOK_PROFILE`	One of `full` (default), `advisory-off`, `minimal`, `off`.

Profile	What stays on
`full` (default)	Every hook
`advisory-off`	Disables pure-stderr advisories: `recurrence-suggest`, `citation-verify`, `error-spike-detector`, `milestone-commit-hook`.
`minimal`	Only the four kit-shipped hooks needed for structural integrity or observability: `no-hand-edit-agents`, `assemble-validate`, `agent-fork-logger`, `session-end-dump`. User-global safety hooks (`no-github-push`, `secrets-guard`, `genesis-leak-guard`, `git-pre-commit-genesis`) are not shipped by the kit but are respected when present in `~/.claude/hooks/`.
`off`	Every hook off (escape hatch — use when debugging hook interactions).

Pipeline (one phase, up to 2 AskUserQuestion batches)

Phase 1 — Show state + pick action

Print current state:

Current KEI_DISABLED_HOOKS: <value or "(unset)">
Current KEI_HOOK_PROFILE:   <value or "full (default)">
Active kit-shipped hooks:   <list of 9 minus disabled set>

AskUserQuestion — What do you want to do?

Disable specific hook(s) — this shell session only
Switch profile — full / advisory-off / minimal / off
Re-enable everything — clear both env vars
Show state only — emit no commands

Phase 2a — Hook multi-select (if picked 1)

AskUserQuestion multi-select over the 10 kit-shipped hook names: assemble-agents, assemble-validate, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, error-spike-detector, milestone-commit-hook, session-end-dump.

Emit:

# Disable selected hooks for this shell session:
export KEI_DISABLED_HOOKS=<comma-joined-names>

For persistence, tell the user to paste into ~/.zshrc / ~/.bashrc by hand. Do NOT edit rc files.

Phase 2b — Profile picker (if picked 2)

AskUserQuestion over full / advisory-off / minimal / off. Emit:

# Switch profile for this shell session:
export KEI_HOOK_PROFILE=<choice>

Phase 2c — Re-enable everything (if picked 3)

Emit directly (no further question):

# Clear all runtime hook overrides (back to full / everything on):
unset KEI_DISABLED_HOOKS KEI_HOOK_PROFILE

Phase 2d — State only (if picked 4)

Stop after the state block.

Rules

Click-only. Every decision is AskUserQuestion. No free-text.
Never execute. The skill prints shell commands as code blocks; the user runs them. Any export from a tool call would evaporate at skill exit — the shell running hooks is a subshell.
No rc edits. If the user wants persistence, we say "paste into your shell rc". The skill MUST NOT modify ~/.zshrc / ~/.bashrc.
RULE 0.4 — no invented hook names. Only the 10 names in Phase 2a are valid choices. Never suggest a name not in the kit.
RULE -1 — NO DOWNGRADE. If the user asks "can I silence all safety hooks?", present tradeoffs; point at KEI_HOOK_PROFILE=off with a warning that patent-IP and generated-file protections also go down.

Final report

=== HOOKS-CONTROL REPORT ===
Action:     <picked option>
Commands:   <N lines emitted>
Scope:      current shell session (unless pasted into rc)
Verify:     `env | grep KEI_` after pasting
Undo:       unset KEI_DISABLED_HOOKS KEI_HOOK_PROFILE

References

hooks/*.sh — each kit hook sources the v0.15.1 runtime-controls block
README.md → "Runtime hook controls" section
~/.claude/rules/recurrence-escalate.md — severity ladder notes that hooks can be silenced at runtime, no rule deletion required

4.6 KiB Raw Blame History