Give the cat-mode flag three settings and retire CAT_MODE_AUTO_INVOKE

[EdbertChan]

Summary

The work style guide can now be off, left for the agent to decide, or always on. One setting controls all three.

Before, two separate settings did overlapping jobs, and they could say different things at once.

Now the one setting takes three words. The old second setting is ignored, and the installer prints a warning when it sees it.

Review Claim

One setting picks between off, let the agent decide, and always on, and the old second setting is retired with a warning.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

An old 1 or 0 behaves exactly as before; only decide changes what gets installed.

Slice Rationale

Bottom of a three-PR stack. This slice holds the installer, the flag reader, the hook text and their tests. The cat-mode skill line and the root README follow as their own review units.

• CATSTACK_CAT_MODE_DEFAULT=off|decide|on (1/true/yes = on; unset/0 = off).
• decide replaces CAT_MODE_AUTO_INVOKE=true: install.sh writes the auto-invoking cat-mode copy only for decide, and removes a generated copy when switched away.
• install.sh reads the flag through engine/hooks/_flags/flags.py, which gains --value. So the value now also comes from ~/.catstack.env, not only this checkout's .env.
• Unknown values and a leftover CAT_MODE_AUTO_INVOKE print a warning instead of being dropped silently.

Non-goals

• No change to which prompts the hook fires on.
• The cat-mode skill text and root README are updated in the next two PRs.

Test Plan

Test Plan

• python3 -m unittest tests.test_install.TestCatModeDefaultInstall with the fix stashed (new tests fail first):

  Ran 9 tests in 135.578s
  FAILED (failures=6)
  

  and with the fix:

  Ran 9 tests in 130.342s
  OK
  

• python3 -m unittest tests.test_install_worktree_repo_dir: failed on the first push because install.sh --help ran the flag lookup in a copy with no flag reader (FAILED (failures=3)). The lookup now runs after argument parsing:

  OK
  

• python3 -m unittest tests.test_install_worktree_repo_dir tests.test_install.TestCatModeDefaultInstall tests.test_cat_mode → Ran 92 tests ... OK; shellcheck install.sh → exit 0
• python3 -m unittest discover -s engine/hooks/_flags/tests → OK (37 tests)
• python3 -m unittest discover -s engine/hooks/cat-mode-default/tests → OK (39 tests)
• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main → unit engine-runtime: 9 file(s), all gates ok

Revert Plan

Revert Plan

• Safe to revert? Yes, after reverting the two PRs stacked on it.
• Revert command: git revert <sha>
• Post-revert steps: re-run ./install.sh; set CAT_MODE_AUTO_INVOKE=true again if decide was in use.
• Data migration? No

🤖 Generated with Claude Code

[EdbertChan]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	Give the cat-mode flag three settings and retire CAT_MODE_AUTO_INVOKE	#744	👈
2	cat-mode: name the on setting of its default flag	#745
3	README: document the three cat-mode flag settings	#746

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fb4dcca. Configure here.}

[EdbertChan]

Revision history

#	Type	Changes	Reason	Date
1	initial	fb4dcca		2026-09-17 01:50 UTC
2	content	fb4dcca → c571574		2026-09-17 01:50 UTC

[mergify]

Queued — the merge queue status continues in this comment ↓.

[EdbertChan]

@Mergifyio queue admin-bypass

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-17 04:13 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #744 on main (282a0f8), stacked on #747 #751
• ✅ Merged — 2026-09-17 04:21 UTC · at 3ef9394af1633b05225025e58f498d7efa5c26d2 · squash

This pull request spent 7 minutes 31 seconds in the queue, including 6 minutes 44 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate