forked from bchanot/claude
docs: phase 2 doc sync (static rule limits, release prep span, code-limits hook, merge tier, .env denies, guard in the mod manifest) — ship-feature phase2-guards
This commit is contained in:
1 parent
fd31640b9c
commit
867a34c326
5 files changed
+11
-8
No files matched your search
+2
-2
@@ -20,7 +20,7 @@ claude-config/
|
||||
├── update-all.sh # One-command update for all components
|
||||
├── Makefile # Unified entry point: make install / doctor / update / test (make help)
|
||||
├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, instruction-load log
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, instruction-load log, code-limits line-width signal
|
||||
├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
|
||||
├── .githooks/ # This repo's own copy of the same hooks
|
||||
├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file
|
||||
@@ -38,6 +38,6 @@ claude-config/
|
||||
|
||||
- `skills/` = entry points you invoke via `/skill-name`
|
||||
- `agents/` = execution units called by skills (never invoked directly by user)
|
||||
- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/<name>` as `<name>@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions
|
||||
- `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/<name>` as `<name>@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions; the mod also redirects a main-loop code write made outside a skill run to a skill (README, "Write guard")
|
||||
- `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually
|
||||
- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go. Where `graphify-out/graph.json` exists, the session-start hook prints the graphify usage rules.
|
||||
+1
-1
@@ -16,7 +16,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
|
||||
|
||||
- **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor raises the effort only, the guess's model holds); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier <phase>` and `/route verbose on` adds `(<phase>: classifier)`.
|
||||
- **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one.
|
||||
- **Phase 2 guards (BDR-125)**: the deterministic half of the gitflow and routing doctrine. Merge gate: `ask` rules on `git merge *`, `bash *gitflow.sh finish*` (it also asks on the quoted `bash "$HOME/.claude/lib/gitflow.sh" finish` every skill types) and `sh *gitflow.sh finish*`: every finish raises one permission prompt, `/close` and `/capitalize` 5C included; a declined prompt stops the flow with "nothing merged, branch kept". Shell forms: `ask` on `sh -c` and its flag forms (`sh -ec`, `bash -lc`, `dash -c`), a bare `bash`/`sh` fed by a heredoc, `bash <(…)`, `/bin/sh`, `/bin/bash`, `/usr/bin/sh`, `/usr/bin/bash`, `/usr/bin/env sh|bash`; `deny` on `awk *system(*`, the flag forms `head|tail|cat * .env*` and `* */.env*` (the plain deny missed `head -5 .env`), and an `rtk read` twin (relative and absolute) for every `cat|head|tail` deny, locked by a census (push-guard T62, T63). Each rule was proven in a saved headless bench in auto mode (`.claude/tasks/plans/2026-11-02-phase2-bench/`); `ask` raising a prompt in an interactive auto-mode session was checked by hand. Not covered, written down as `autoMode.soft_deny` "Static rule blind spots": `$(…)` in command position, a quoted literal argument, inline interpreters, `… | bash -s`, a sourced `gitflow_finish`, and `git -C <dir> merge`. Routing guard in model-router: a main-loop Edit, Write or NotebookEdit of a code file (config included; `.md`, `.txt`, the project's `.claude/` outside `worktrees/` and `docs/` are free) is redirected ("code is written inside a skill run. Enter /hotfix, /feat, /bugfix or /ship-feature, or re-enter the skill you were running") until a skill ran on the main loop in the session, a phase was declared this turn, or a typed `/route` holds; sub-agents write freely; `/route clear`, `/route off` and `/clear` re-arm it; a `/model` hand pick does not open it; a register.ts reload resets it. A new `autoMode.hard_deny` entry says a redirect is followed, never routed around, and `permissions.ask` is never edited to pass a gate. code-limits hook (PostToolUse, `Edit|Write`): the lines a file gained over 80 columns, in our code only (`lib/code-origin.sh`), once per file per session, as context, never a block; silent in a repo the origin check calls foreign, this one included unless `git config claude.origin ours`.
|
||||
- **Phase 2 guards (BDR-125)**: the deterministic half of the gitflow and routing doctrine. Merge gate: `ask` rules on `git merge *`, `bash *gitflow.sh finish*` (it also asks on the quoted `bash "$HOME/.claude/lib/gitflow.sh" finish` every skill types) and `sh *gitflow.sh finish*`: every finish raises one permission prompt, `/close` and `/capitalize` 5C included; a declined prompt stops the flow with "nothing merged, branch kept". Shell forms: `ask` on `sh -c` and its flag forms (`sh -ec`, `bash -lc`, `dash -c`), a bare `bash`/`sh` fed by a heredoc, `bash <(…)`, `/bin/sh`, `/bin/bash`, `/usr/bin/sh`, `/usr/bin/bash`, `/usr/bin/env sh|bash`; `deny` on `awk *system(*`, the flag forms `head|tail|cat * .env*` and `* */.env*` (the plain deny missed `head -5 .env`), and an `rtk read` twin (relative and absolute) for every `cat|head|tail` deny, locked by a census (push-guard T62, T63). Each rule was proven in a saved headless bench in auto mode (`.claude/tasks/plans/2026-11-02-phase2-bench/`); `ask` raising a prompt in an interactive auto-mode session was checked by hand. Not covered by a static rule, written down as `autoMode.soft_deny` "Static rule blind spots": `$(…)` in command position, a quoted literal argument, inline interpreters and a sourced `gitflow_finish`; `git -C <dir> merge` escapes the merge `ask` and is not in that entry. A script piped into `bash -s` is refused by the existing deny `Bash(* | bash -*)`. Routing guard in model-router: a main-loop Edit, Write or NotebookEdit of a code file (config included; `.md`, `.txt`, the project's `.claude/` outside `worktrees/` and `docs/` are free) is redirected ("model-router: code is written inside a skill run. Enter /hotfix (≤2 files, obvious fix), /feat, /bugfix or /ship-feature, or re-enter the skill you were running, then make this edit") until a skill ran on the main loop in the session, a phase was declared this turn, or a typed `/route` holds; sub-agents write freely; `/route clear`, `/route off` and `/clear` re-arm it; a `/model` hand pick does not open it; a register.ts reload resets it. A new `autoMode.hard_deny` entry says a redirect is followed, never routed around, and `permissions.ask` is never edited to pass a gate. code-limits hook (PostToolUse, `Edit|Write`): the lines a file gained over 80 columns, in our code only (`lib/code-origin.sh`), once per file per session, as context, never a block; silent in a repo the origin check calls foreign, this one included unless `git config claude.origin ours`.
|
||||
- **model-router ask before Fable**: before a route lifts the main loop, or a rowed agent, onto Fable from another model, the mod asks once per span with the origin (skill, agent, `route` tool, `/route`), the phase and its `about` line, the model and the effort: `Fable`, `Opus instead (big tier)` (the span resolves through the `big` tier at the phase's effort, offered only while Opus is up) or `Stop asking this session` (paused until `/clear`). A best-tier skill the model loads counts as a skill row; a spawn keeps one answer per agent type per session. Never headless (`-p`) or inside a sub-agent; a dismissed dialog runs Fable; no answer is written to `routing.json` (`confirmed` included). `routing.json` gains `askTier` (`best`, or `false` to turn it off; the machine config wins), set by `/route ask-tier on|off`; `/route show` prints `ask-tier:`. Known limit: when a Fable breaker hold or a cold-read cap lapses later, main upgrades without asking. Tests: `mods/model-router/hooks/register.test.ts` (TIER).
|
||||
- **/explain-diff skill**: turns a change (commit, range, branch, merge, PR, staged or uncommitted work) into one self-contained HTML page saved outside the repo, under `~/Documents/explanations/<project>/YYYY-MM-DD-<slug>.html`. The page has a background, an intuition built on toy data with HTML diagrams, a code walkthrough grouped by concern and a 5-question interactive quiz. Adapted from Geoffrey Litt's explain-diff gist. A bundled template (light and dark, works offline) and a checker (`scripts/check_explanation.py`: file name, location, sections, quiz, code escaping, no ASCII art, no em-dash) hold every page to the same floor. Routing row `reflect`; profiles full, max and dev.
|
||||
- **Project path rules (CLAUDE.md split)**: `lib/project-rules.sh` (`check`, `matches`, `sections`, `extract`, `emit`, optional `-C <dir>`) is the glob oracle for `.claude/rules/<name>.md` rules, one-line `paths:` frontmatter, loaded on Read of a matching file; suite `lib/tests/project-rules.test.sh`. `/onboard split` classifies an existing project CLAUDE.md section by section behind a gate and moves the path-bound ones into rules on a `chore/claude-md-split` branch. `extract` also moves a `###` subsection (heading passed as `'### <title>'`; a bare heading stays `##`), which ends at the next heading of level 3 or less outside a fence, and `sections --depth 3` lists each `##` section's subsections with their sizes, so `/onboard split` can move a path-bound subsection out of an always-on parent (one `### <title>` row; a row's parent is never itself a move row). `extract` refuses an absolute `<out>`, one with a `..` part, or one that already exists (a dangling symlink included), with rc 2 and the reason on stderr, and leaves the source CLAUDE.md untouched when the rule directory or file cannot be written. `/onboard` and `/init-project` emit `docker`, `testing` and `ci` rules from `templates/project-rules/` when their globs match. This repo's CLAUDE.md now keeps its header, Health Stack and a pointer; four sections load as path rules.
|
||||
|
||||
@@ -88,7 +88,7 @@ model-router row, their
|
||||
| feater, hotfixer, bugfixer | sonnet (pinned) | executors — code from a closed plan (feat), fix from a closed diagnosis (bugfix), fix-bundle appliers |
|
||||
| verifier | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) |
|
||||
| security-auditor | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) |
|
||||
| commit-changer, release-executor, code-cleaner | sonnet (pinned) | dispatched execution — grouping+commit / release spans / approved cleanup (audit + approval gates stay in the dispatcher) |
|
||||
| commit-changer, release-executor, code-cleaner | sonnet (pinned) | dispatched execution — grouping+commit / release prep span / approved cleanup (audit + approval gates stay in the dispatcher) |
|
||||
| onboarder, scaffolder, refactorer, validator-analyzer, plugin-probe | sonnet (pinned) | workers — config generation, scaffold, refactor, deterministic W3C/WCAG runner, mechanical plugin probe |
|
||||
| status-reporter | haiku (pinned) | mechanical collector |
|
||||
| analyzer, plan-challenger, plugin-advisor | opus (pinned) | dispatched judgment — pre-plan analysis, 3-lens adversarial plan challenge (`/ship-feature` STEP 2b), plugin-fit reasoning |
|
||||
@@ -415,9 +415,10 @@ on 2026-11-02). The matcher sees through `&&`, `;`, `|`, `env`, `timeout`,
|
||||
`xargs` and simple assignments. The phase 2 rules ask on `sh -c` and its flag
|
||||
forms (`sh -ec`, `bash -lc`, `dash -c`), a bare `bash` or `sh` fed by a
|
||||
heredoc, process substitution (`bash <(…)`) and the absolute shells `/bin/sh`,
|
||||
`/bin/bash`, `/usr/bin/sh`, `/usr/bin/bash`, `/usr/bin/env sh|bash`; they do
|
||||
not cover a script piped into `bash -s`, a sourced `gitflow_finish` or
|
||||
`git -C <dir> merge`. The matcher cannot see `$(…)` in command position, a
|
||||
`/bin/bash`, `/usr/bin/sh`, `/usr/bin/bash`, `/usr/bin/env sh|bash`. A script
|
||||
piped into a shell (`… | bash -s`) is already refused by the deny
|
||||
`Bash(* | bash -*)`. A sourced `gitflow_finish` and `git -C <dir> merge`
|
||||
escape the static rules. The matcher cannot see `$(…)` in command position, a
|
||||
quoted literal argument or an inline interpreter: those rest on the
|
||||
auto-mode classifier (`autoMode.soft_deny`, "Static rule blind spots"). The
|
||||
rtk hook passes any command its registry asks about or denies through
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "model-router",
|
||||
"version": "0.1.0",
|
||||
"description": "Routes every model request (main loop and sub-agents) to the model and effort its phase deserves, from a user config, a route tool, /route and skill or prompt rules.",
|
||||
"description": "Routes every model request (main loop and sub-agents) to the model and effort its phase deserves, from a user config, a route tool, /route and skill or prompt rules, and redirects a main-loop code write made outside a skill run into a skill.",
|
||||
"author": {
|
||||
"name": "bchanot"
|
||||
}
|
||||
|
||||
@@ -125,6 +125,7 @@ no separate setting for this.
|
||||
|
||||
- `Read(**/.env)` only blocks the Read tool. `Bash(cat .env)` bypasses it unless separately denied.
|
||||
→ Use `.claudeignore` for hard file exclusion regardless of tool.
|
||||
- This config denies `cat`, `head` and `tail` of `.env*` (flag forms included, e.g. `head -5 .env`) and the `rtk read` twin of every such deny; `lib/tests/push-guard.test.sh` (T62) fails when a twin is missing.
|
||||
- `disableBypassPermissionsMode: "disable"` prevents switching to bypass mode mid-session.
|
||||
- Prefer `autoMode.soft_deny` over `allow` for anything touching external systems.
|
||||
- `deny` in `~/.claude/settings.json` cannot be overridden by project-level `allow` — deny always wins.
|
||||
@@ -143,6 +144,7 @@ local trace, and the brief had authorized it. What holds now, by tier:
|
||||
| Docker volume drops, `system prune`, `compose down -v`, `--privileged`, the docker socket, `-v /:` | `permissions.deny` | Promoted from `soft_deny`: no in-session clearance for data drops. |
|
||||
| Git history destruction (`push --delete`/`--mirror`/`:ref`/`--force-with-lease`, `branch -D`, `filter-branch`, `reflog expire`, `stash clear`/`drop`, `clean -f`), `--no-verify`, `core.hooksPath` | `permissions.deny` | A remote is the backup; nothing rewrites or deletes what it holds. |
|
||||
| Writing the human-only `gitflow.*` toggles: any `git … config` spelling, section remove/rename, `git -c`, the git config env overrides, Edit/Write of git config files | `permissions.deny` | Claude never flips the mode that binds it. Side effect: the trailing glob also matches the bare read, so Claude cannot read `gitflow.autopush` through `git config`; hooks and `lib/gitflow.sh` still do, and skills read it through `gitflow.sh push-mode`. |
|
||||
| Merging: `git merge`, `bash`/`sh` `…gitflow.sh finish` | `permissions.ask` | `finish` runs only on an explicit human signal: one prompt per merge, and a declined prompt merges nothing. `git -C <dir> merge` and a sourced `gitflow_finish` escape the static rules; the sourced form falls to `autoMode.soft_deny` "Static rule blind spots". |
|
||||
| Pushing in manual-push mode (`gitflow.autopush false`, or any invalid value) | `hooks/push-guard.sh` (PreToolUse) + `autoMode.soft_deny` | An `ask` would prompt, and a click would push. The hook denies the direct forms; the soft_deny covers scripted, aliased, subshell and sub-agent pushes, and a request in the turn does not clear it: the user types `! git push`. |
|
||||
| Destructive tool against a local path (variable, `~`, `..`, wildcard, outside cwd/tmp), even as a trace or a rehearsal a brief allows | `autoMode.hard_deny` | A pattern cannot express "the target resolves outside the project"; the classifier can. A sub-agent brief carries no user authority. |
|
||||
| `docker rm -f`, bind mount outside cwd; discarding uncommitted work | `autoMode.soft_deny` | Recoverable or user-intended in the turn. |
|
||||
|
||||
Reference in new issue
Block a user