Skip to content

README: name the reflect enforcement setting and its four hooks #501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EdbertChan wants to merge 1 commit into
base: stack/EdbertChan/docs/reflect-enforcement-flag-readme/reflect-automate-me-enforcement-opt-behind-one--82a63478
Choose a base branch
from
Open

README: name the reflect enforcement setting and its four hooks #501

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ Full sourcing notes, including what was left out and why: [docs/provenance.md](d
| --- | --- |
| `diu-stop` | End of turn: did the answer skip the brevity rule? |
| `bug-complaint-leak` | Bug-complaint prompts: search class, not just local grep. |
| `reflect-on-thrash` | Thrash detected: defer reflect until the session ends. Do not steal the current turn. |
| `reflect-on-thrash` | Thrash detected: defer reflect until the session ends. Do not steal the current turn. Off unless `CATSTACK_REFLECT_ENFORCEMENT=1` (see below). |
| `restart-risk-check` | Thin-evidence "just restart it" claims. |
| `demo-freeze` | Live demo window: don't edit the thing being filmed. |
| `frustration-watchdog` | User-frustration signals. |
Expand All @@ -175,6 +175,27 @@ Full sourcing notes, including what was left out and why: [docs/provenance.md](d

Details live in each hook's README under `engine/hooks/<name>/`.

### Reflect enforcement (opt-in)

Four hooks push you toward `/reflect` and `automate-me`. All four are off
unless `CATSTACK_REFLECT_ENFORCEMENT` is on:

| Hook | What it does when on |
| --- | --- |
| `scope-lock` | after a second scope correction, stops every tool until you type `/reflect` and `automate-me` |
| `reflect-on-thrash` | asks for a reflect at the end of a thrashy session |
| `wrong-check-reflect` | queues a judge on a retraction-shaped reply |
| `verdict-flip-watch` | notes a verifier that passed and then failed |

```sh
echo 'CATSTACK_REFLECT_ENFORCEMENT=1' >> ~/.catstack.env
```

The environment, `$CATSTACK_ENV_FILE`, the repo's `.env` and `~/.catstack.env`
are read in that order. `frustration-watchdog` is not in this class -- it
enforces the live-demo "end the wait" rule and never mentions reflect.
Details: [engine/hooks/_flags/README.md](engine/hooks/_flags/README.md).

### Session mine (opt-in)

Hourly local scan of Claude / Cursor / Codex transcripts for repeated user pokes, plus DORA-for-agents metrics. Off by default:
Expand Down
Loading