chore: Claude Code scaffolding (CLAUDE.md, .claude/settings.json) + IDEAS backlog - #82
Conversation
…klog Claude Code best-practice scaffolding for contributors: a layered CLAUDE.md (accurate to the code), a project-level .claude/settings.json (read-only allowlist + destructive-command deny list), and IDEAS.md, a scored improvement backlog from a read-only best-practice sweep. Docs/config only; no source or runtime behavior changes.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 573081925e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - The session-start hook re-injects `TASK_STATE.md` after Claude compaction. | ||
| - The pre-tool-use hook enforces a write boundary for write-capable tools. | ||
| - The pre-tool-use hook blocks writes outside the current worktree. | ||
| - The pre-tool-use hook (BL-2) blocks a curated set of destructive command tokens by substring-matching the full command: force pushes (`--force`/`-f`), `git reset --hard origin`, `git clean -fdx`, `rm -rf` of `/`/`~`/`--no-preserve-root`, `--no-verify` commits/pushes/merges, DB-destructive commands (`DROP`/`TRUNCATE`, `prisma migrate reset`, `drizzle-kit push --force`, `supabase db reset`), infra-destroy commands (`terraform destroy`, `kubectl delete namespace`, `docker … up -d` against prod), `npm`/`cargo publish`, and secret-file reads (`cat .env`/credentials/`id_rsa`). |
There was a problem hiding this comment.
This safety note says BL-2 blocks --no-verify commits/pushes/merges, but the generated PreToolUse blocklist in src/core/hooks.ts has no no-verify pattern, and the newly committed .claude/settings.json deny rules do not apply to auto sessions because line 160 notes they run with --dangerously-skip-permissions. In autonomous sessions, an agent can still run git commit --no-verify unless the hook is updated, so the guide overstates a guardrail that callers may rely on for pre-commit enforcement.
Useful? React with 👍 / 👎.
| { | ||
| "permissions": { | ||
| "allow": [ |
There was a problem hiding this comment.
Adding a tracked .claude/settings.json means every ccmux worktree for this project already contains this file before autoCommand calls installSessionHooks; writeSettingsOverlay() then skips writing its hook configuration when the settings file exists, so ccmux auto on this repo launches with --dangerously-skip-permissions but without the generated Stop/SessionStart/PreToolUse hooks. In that scenario TASK_STATE loop control and the write-boundary/destructive-command guards are not registered; the committed settings need to be merged with the generated overlay or the installer needs to update existing settings.
Useful? React with 👍 / 👎.
| already on `main` at the time of writing. | ||
|
|
||
| ## Done / not needed (verified against the codebase) | ||
| - **Windows SessionStart hook path bug** — `writeSessionStartHook` embedded a raw Windows path; fixed in PR #81 (POSIX-normalize + regression test). |
There was a problem hiding this comment.
This moves the Windows SessionStart hook path bug into the Done section, but current writeSessionStartHook() still embeds ${worktreePath} directly in the generated bash script instead of POSIX-normalizing it like writeStopHook() does. On native Windows worktrees, the compaction recovery hook can still fail to find TASK_STATE.md, so marking this as fixed hides an unresolved Windows-only failure from the backlog.
Useful? React with 👍 / 👎.
…ing-dev-infra # Conflicts: # .claude/settings.json
1 participant
Additive docs/config only — no source or runtime behavior changes.
What
CLAUDE.md— layered, code-accurate project guide (Quick Start → Architecture → Commands → Testing → Safety/Guardrails → Extending). The Safety section is scoped precisely to what the BL-2 hook actually enforces (a curated destructive-token blocklist, not a general filter), and notes thatpermissions.denyis not enforced under--dangerously-skip-permissions— the PreToolUse hook is the sole guard there..claude/settings.json— read-only permission allowlist (the realpackage.jsonscripts + safe read-only git) plus a destructive-commanddenylist (force-push, hard reset, force-clean,--no-verify, recursive force-delete).IDEAS.md— scored improvement backlog (T1/T2/T3) from a best-practice sweep, with already-done items marked.Notes
.claude/is not gitignored;settings.jsonvalidated as JSON..editorconfig/CONTRIBUTINGto avoid overlap with existing unpushedtask5-editorconfig/task6-contributingwork.main.