docs: 3.0.0 migration section, changelog deny fixes

This commit is contained in:
bchanot committed 2026-11-12 15:50:53 +01:00
1 parent 36c8ccd17e
commit ed67c52194
2 files changed
+21 -5

No files matched your search

+7 -5
View File
@@ -15,7 +15,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `audit`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run <phase>`), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget <name|all|projects>|<phase>|model=<alias|id> effort=<level>|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch (a `/model` hand pick excepted) runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions.
- **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 12 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`.
- **model-router `/model` scope**: a `/model <name>` typed in the composer, or a pick in the `/model` picker, with a model the table knows asks where it applies. The picker's switch is held first (PreModelSwitch deny; the engine prints that a hook blocked it); a pick while another dialog is open is refused with `answer the open dialog first`. This project writes the full id as `model` into the project's `.claude/settings.local.json` (created if absent, refused through a link) and sets a sticky model route. This conversation sets the sticky route only. Everywhere runs the native `/model` (user `settings.json`). Both non-native answers drop the run slot and keep a sticky effort. With the picker's Default, an unknown name, a headless run or another origin, the native command runs with no question. A model chosen in that dialog always switches: it bypasses the cold-read caps and the `mainUpgrade` / `mainModelSwitch` flags, and while it is marked down or outside a known window it waits and the automatic chain decides. A native switch or `/clear` drops it; `/route model=` keeps the caps. Known limits: the `/config` Model row still writes user `settings.json`; a dialog never answered has no timeout. Tests: `mods/model-router/hooks/register.test.ts`.
- **Manual-push mode**: `git config gitflow.autopush false` (human-set) now stops every push the gitflow lib makes, not only the post-commit / post-merge hooks. `gitflow start` and `finish` branch, commit and merge locally and push nothing; `gitflow delete` leaves the `origin/` copy in place and prints `git push origin --delete <br>` for the user to run. `hooks/unpushed-guard.sh` stays silent at turn end in this mode and opens each session with one `ℹ manual push mode:` line counting the commits no remote holds across every local branch; an unparseable or unreadable `gitflow.autopush` value is treated as manual push mode too, and that line names it. `hooks/push-guard.sh` (PreToolUse, `Bash|Monitor`) refuses any `git push` Claude types while `gitflow.autopush` reads false in the session cwd or in a literal `-C`/`cd` directory the command names (global config counts outside a repo); the refusal tells the user to run it with `! git push`. It reads the mode through the same lib verb as every other reader and fails closed: an unparseable or unreadable value reads as manual, and an internal error, a missing `lib/gitflow.sh`, more than 20 distinct directory tokens in one command (capped before any token is classified), a `cd`/`-C` directory token mixing quoted and unquoted parts, or a payload jq cannot parse whose raw text looks like a push refuse the push (these pathological cases fire in auto mode too). Directory tokens are read as whole shell words, adjacent quoted segments and backslash escapes included. Once the text looks like a push, the command is split into simple commands (quotes, escapes, separators, heredoc bodies dropped) and a push must be git's own subcommand in one of them: `grep "git push"`, `git log -S "git push"`, `git config --get push.default`, `git stash push`, a heredoc quoting a push or a commit message naming one are allowed; `bash -c` scripts are re-checked, wrappers (`sudo`, `env`, `eval`, `xargs`, `timeout`, `git subtree`...) and assignments keep the text verdict. The misses listed in its header fall to a new `autoMode.soft_deny` rule that no request in the turn clears. The session banner adds `🔒 push : manual (autopush=false) — ! git push` when the key reads false, and `🔒 push : manual (autopush bad) — ! git push` when the value is invalid. Skills read the mode through a new lib verb, `bash ~/.claude/lib/gitflow.sh push-mode`: it prints `auto`, `manual` or `invalid` (rc 0) and names an invalid value on stderr (printable characters only, 64 at most). It is the one reader a skill may call, since the `git config` read of the key is denied to Claude. Skills push nothing on their own, except the `/release-candidate` tag in auto-push mode on an explicit go. Every "on origin" or "not pushed" line they print comes from `git rev-list --count origin/<br>..<br>` read after the fact, with the complete `! git …` command when something is left for the user to push. An invalid value (anything but unset, true or false, or a read that fails) is manual push mode for every reader and is named where it is read (see Fixed). Tests: `lib/gitflow-test.sh` T11b (push-mode verb), T18m and T18q blocks, `lib/tests/unpushed-guard.test.sh` T10-T16, `lib/tests/push-guard.test.sh` (98 checks).
- **Manual-push mode**: `git config gitflow.autopush false` (human-set) now stops every push the gitflow lib makes, not only the post-commit / post-merge hooks. `gitflow start` and `finish` branch, commit and merge locally and push nothing; `gitflow delete` leaves the `origin/` copy in place and prints `git push origin --delete <br>` for the user to run. `hooks/unpushed-guard.sh` stays silent at turn end in this mode and opens each session with one `ℹ manual push mode:` line counting the commits no remote holds across every local branch; an unparseable or unreadable `gitflow.autopush` value is treated as manual push mode too, and that line names it. `hooks/push-guard.sh` (PreToolUse, `Bash|Monitor`) refuses any `git push` Claude types while `gitflow.autopush` reads false in the session cwd or in a literal `-C`/`cd` directory the command names (global config counts outside a repo); the refusal tells the user to run it with `! git push`. It reads the mode through the same lib verb as every other reader and fails closed: an unparseable or unreadable value reads as manual, and an internal error, a missing `lib/gitflow.sh`, more than 20 distinct directory tokens in one command (capped before any token is classified), a `cd`/`-C` directory token mixing quoted and unquoted parts, or a payload jq cannot parse whose raw text looks like a push refuse the push (these pathological cases fire in auto mode too). Directory tokens are read as whole shell words, adjacent quoted segments and backslash escapes included. Once the text looks like a push, the command is split into simple commands (quotes, escapes, separators, heredoc bodies dropped) and a push must be git's own subcommand in one of them: `grep "git push"`, `git log -S "git push"`, `git config --get push.default`, `git stash push`, a heredoc quoting a push or a commit message naming one are allowed; `bash -c` scripts are re-checked, wrappers (`sudo`, `env`, `eval`, `xargs`, `timeout`, `git subtree`...) and assignments keep the text verdict. The misses listed in its header fall to a new `autoMode.soft_deny` rule that no request in the turn clears. The session banner adds `🔒 push : manual (autopush=false) — ! git push` when the key reads false, and `🔒 push : manual (autopush bad) — ! git push` when the value is invalid. Skills read the mode through a new lib verb, `bash ~/.claude/lib/gitflow.sh push-mode`: it prints `auto`, `manual` or `invalid` (rc 0) and names an invalid value on stderr (printable characters only, 64 at most). It is the one reader a skill may call, since the `git config` read of the key is denied to Claude. Skills push nothing on their own, except the `/release-candidate` tag in auto-push mode on an explicit go. Every "on origin" or "not pushed" line they print comes from `git rev-list --count origin/<br>..<br>` read after the fact, with the complete `! git …` command when something is left for the user to push. An invalid value (anything but unset, true or false, or a read that fails) is manual push mode for every reader and is named where it is read (see Fixed). Tests: `lib/gitflow-test.sh` T11b (push-mode verb), T18m and T18q blocks, `lib/tests/unpushed-guard.test.sh` T10-T16, `lib/tests/push-guard.test.sh`.
- **extract-guard hook**: `hooks/extract-guard.sh` (PreToolUse, `Bash|Monitor`) refuses a package or archive extraction into `/` or a system directory (`/usr`, `/etc`, `/bin`, `/sbin`, `/lib*`, `/boot`, `/opt`, `/var`, `/srv`, `/root`, `/sys`, `/proc`, `/dev`; `/var/tmp` and `$HOME` stay free), after `dpkg -x` into `/` replaced the usr-merge `/bin` and `/lib` symlinks with real directories. Watched: `dpkg -x`, `dpkg-deb -x`/`-R`, `tar x` (`bsdtar`, `gtar` too), `unzip`, `cpio -i` and `-p`, recursive `cp`; the destination comes from `-C`/`--directory`, `unzip -d`, `cpio -D`, `cp -t` or the last argument, or from a `cd` before the command. Every quoted word holding a blank is re-scanned, so a script run through `ssh`, `vaas-cli ssh`, `bash -c`, `sudo sh -c` or `find -exec` is checked, as are `$(…)`, backticks and heredoc bodies. A destination it cannot resolve (`$VAR`, `$(…)`, a glob or brace) is refused, and so are a command over 64 KiB that names a watched tool, nesting deeper than three levels and an awk failure (fail closed). The refusal says to list the archive (`dpkg -c`, `tar tf`, `unzip -l`), extract into the literal path `mktemp -d` prints and use PATH or PYTHONPATH; a real system install is the user's to run with `!`. With jq, awk, grep, sed, tr or wc missing it warns once on stderr and allows. The misses listed in its header (a destination built outside the text, old-style `tar xfC`, archive members escaping a safe `-C`) fall to a new `autoMode.soft_deny` line. Doctrine bullet in `CLAUDE.global.md` § Destructive tools & data loss. Tests: `lib/tests/extract-guard.test.sh` (134 checks).
- **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)`.
@@ -48,7 +48,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
- Doctrine ceiling: the main loop on Fable writes no code past the `/hotfix` scope and hands larger work to `/feat` or `/bugfix` (Sub-agents rule in `CLAUDE.global.md`). README and the plan-challenge citers (`lib/challenge-plan.md`, `agents/plan-challenger.md`) now say the main loop runs on the `opus` session model and reaches Fable through best-tier rows.
- `/deploy` runs on the `verify` row (sonnet/xhigh, was `apply` sonnet/low). The row ships as such, its `changed` entry is dropped from `routing.json`, and the frontmatter floor follows (`effort: xhigh`).
- `lib/model-gate.md` calls the model-router `route` tool and takes its answer as the witness; with the mod off the gate stops and names `/route on`. The `model:` / `effort:` frontmatter of agents and skills is now the off-state floor, census-locked equal to the rows (`lib/tests/effort-routing.test.sh`; a row changed through the first-use dialog passes with a `WARN floor drift` line while its frontmatter still holds the shipped value). `analyzer` effort goes from high to xhigh. Built-in judgment dispatches carry an explicit `effort=`.
- `settings.json` denies every write form of the human-only `gitflow.*` keys (18 entries): any `git … config` spelling, section remove/rename, `git -c`, the git config env overrides, and Edit/Write of `.git/config`, `.gitconfig` and `~/.config/git/config`. Side effect: Claude can no longer read `gitflow.autopush` through `git config` either; hooks and `lib/gitflow.sh` still read it. The `hard_deny` rule on routing around a guardrail now names PreToolUse hook refusals.
- `settings.json` denies every write form of the human-only `gitflow.*` keys (14 entries): any `git … config` spelling, section remove/rename, `git -c`, the git config env overrides, and Edit of `.git/config`, `.gitconfig` and `~/.config/git/config`. Side effect: Claude can no longer read `gitflow.autopush` through `git config` either; hooks and `lib/gitflow.sh` still read it. The `hard_deny` rule on routing around a guardrail now names PreToolUse hook refusals.
- `gitflow start` and `finish` warn on stderr when a base is behind origin and cannot fast-forward, instead of a silent `git pull --ff-only || true` (T18l, T18n).
- `/close` (`/capitalize` STEP 5C) no longer runs its own push of develop: `gitflow finish` already pushes develop in auto-push mode (BDR-095). The closing line reports the real state, read after the merge: pushed, manual push mode with the `! git push origin develop` to run, not on origin, push failed, or an invalid `gitflow.autopush` value named and treated as manual push mode. A finish whose merge landed but whose branch delete failed (rc 5/2/6) still reports the push state.
- `/client-handover` no longer asks "Push to origin now?" and no longer pushes: the hooks had already pushed in auto-push mode, and push-guard refuses it in manual mode. The agent reads the branch's ahead count after the fix-loop commits, at the deploy pause and before each end report. A pending push is handed to the user as `! git push -u origin <branch>` before the deploy pause, and both reports carry a `Push:` line. A branch name outside `^[A-Za-z0-9._/][A-Za-z0-9._/-]*$` is never interpolated into a command.
@@ -89,6 +89,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
- `/guardrails` residuals. The live probe fails closed in more cases: every followed same-host redirect is charged to the request budget, and a budget that runs out mid-redirect reads ERROR; an anon-read or cross-user answer that is not a 200 or a refusal, or a 200 whose body is empty, over 1 MB or not JSON, reads SKIPPED instead of CLOSED; a rate-limit burst cut short by the budget or the transport reads SKIPPED; the source-map probe tries every candidate map of a script instead of stopping at the first it cannot confirm, and a `data:` map is OPEN whatever its encoding; the fields probe no longer flags metadata keys (`token_type`, `has_password`, `next_page_token`). The plan's Supabase `url` must be an http(s) url when tables or cross-user paths are set, `supabase.tables` must be a list of strings, and the `--authorized` refusal names both hosts. Scanner and probe text output strip control characters from file names and remote strings. Static rules lose false positives (hydrated state read per export chunk, webpack dev configs, `data-*` names with a UI suffix such as `-toggle` or `-strength`, GraphQL `_bool_exp` and capitalised types under `$where`) and gain detections: Go backtick SQL in `fmt.Sprintf`, `rf` / `fr` and triple-quoted Python f-strings, `sql.raw` / `db.raw` / `trx.raw`, an empty `.select()` on a users table, a hidden input spanning lines, a Rust `{}` argument to a DB shell tool, a large public `.map` whose head holds `"sources"`. Tests: `lib/tests/guardrails-scan.test.sh`, `lib/tests/guardrails-probe.test.sh`.
- `lib/tests/mods.test.sh` judges `claude plugin validate` by the exit code of `--strict` instead of scraping its output: per-file warnings exit 1 and fail the mod, and the advisory plugin-directory section that CLI 2.1.306 prints (`ICON_MISSING`, not blocking) no longer counts as a failure, as the old whole-output `warning` grep did. A failure prints the `✘` / `error:` lines and the `--strict` command to rerun. A positive control writes two scratch manifests in a temp dir and checks that `--strict` passes the clean one and fails the one with warnings, so the gate cannot pass vacuously.
- `settings.json` denies `Bash(rtk read * .env*)` and `Bash(*/rtk read * .env*)`: the `rtk read` twin of the flag-form `cat * .env*` deny was missing, so an `rtk read` with a flag before a root `.env` passed. push-guard T63 pins both.
- Two 2.0.0 deny entries never matched: `Bash(docker run * -v /:*)` and `Bash(git push * :*)`, mixed forms with a `*` before the trailing `:*`. The working forms `Bash(docker run * -v /:/*)` and `Bash(git push * :**)` were added (ac23cc6) and the dead ones dropped (12c3534). push-guard T42 forgives the two removals while `version.txt` is 3.0.0 or lower.
- `hooks/session-start.sh` bounds its `memory.sh check` with `timeout 2` when `timeout` is installed: a hung check no longer stalls every session start.
- `lib/memory.sh` reads a path shaped like an awk assignment (`x=1.md`, `a=b`) as a file: `add --body-file`, `check` and `upgrade` prefix it with `./`, where awk took it for a `var=value` operand and read stdin. Tests: `lib/tests/memory.test.sh` T19, T19b, T19c.
- Hook-running test suites source `lib/tests/claude-stub.sh`: a logging `claude` stub goes first on PATH and the suite exits if it is not the one resolved, so a hook run can no longer start a real session that re-runs the hook (fork bomb). Suite `lib/tests/claude-stub.test.sh`.
@@ -668,9 +669,10 @@ Upgrading from 1.x: see [MIGRATION.md](./MIGRATION.md#upgrading-an-existing-mach
the plugin while the 7 symlinks are still linked, delete the
`skills/<7>` symlinks or re-run `make plugin` to avoid duplicate skill
descriptions.
- The macOS portability fix was verified on macOS only. Every replacement is
meant to behave identically on GNU/Linux; a Linux `make test` run is still
to be done after 2.0.0.
- The macOS portability fix was verified on macOS at release time. A Linux
`make test` run after 2.0.0 passes, so the replacements hold on GNU/Linux
too.
## [1.5.0] — 2026-09-13
### Added
+14
View File
@@ -306,3 +306,17 @@ To migrate, run `bash ~/.claude/lib/memory.sh -C <project> upgrade` on a clean `
## Claude.ai-synced skills off (2026-11-09)
`settings.json` now sets the claude.ai-synced skills to `"off"` in `skillOverrides`. The change was measured on Claude Code 2.1.319: run `claude --version` on a machine before pulling it there. A project that uses one of those skills brings it back with `{"skillOverrides": {"<name>": "on"}}` in its `.claude/settings.local.json`.
## Upgrading to 3.0.0
3.0.0 removes the typed `/effort-*` commands and narrows what Claude runs without asking. Run the machine steps of "Profiles and packs (2026-11)" in the 2.0.0 section first: they cover the pull, `make link`, `make plugin` and `make doctor`. Then check the items below.
- **Effort commands removed**: `/effort-low` through `/effort-max` no longer exist, nor do `lib/effort-pins.sh`, `lib/effort-pins.txt` and `lib/model-check.sh`. Type `ultrathink` in a prompt to raise one turn's effort, or `/route effort=max` to hold it until `/route clear`. The model-router rows now set each skill's model and effort. With the router off, a skill that goes through `lib/model-gate.md` stops and names `/route on`.
- **Profiles**: `skills-disabled/`, `lib/toggle-external.sh`, the `.profile` files, `.active-profile` and `make profile-reset` are gone. A profile is now a `lib/profiles/<name>.json` settings fragment; `backend` became `dev` and `web-full` became `full`. Re-set each project with `bash ~/.claude/lib/profile.sh set <profile>`, and turn Higgsfield on with `bash ~/.claude/lib/profile.sh enable higgsfield`.
- **Code edits run inside a skill**: model-router redirects a main-loop Edit or Write of a code file (config included) to `/hotfix`, `/feat`, `/bugfix` or `/ship-feature`. Markdown, `.txt`, `docs/` and the project's `.claude/` stay free, sub-agents write freely, and a typed `/route` lifts the redirect.
- **Merges ask**: `gitflow.sh finish` and `git merge` raise a permission prompt every time, `/close` and `/capitalize` included. Declining stops the flow with "nothing merged, branch kept". `sh -c` and its flag forms (`bash -lc`, `dash -c`), a bare `bash` or `sh` fed by a heredoc, `bash <(…)` and `/bin/sh`, `/bin/bash`, `/usr/bin/env sh|bash` ask too.
- **`gitflow.*` keys are yours alone**: Claude can no longer read or write them through `git config`, `git -c` or the git config env overrides, nor Edit `.git/config`, `.gitconfig` or `~/.config/git/config`. A custom skill that read `gitflow.autopush` through `git config` calls `bash ~/.claude/lib/gitflow.sh push-mode` instead; it prints `auto`, `manual` or `invalid`.
- **Commits on `main` and `develop`**: the pre-commit exemption shrank from all of `.claude/**` to `.claude/memory/`, `.claude/tasks/`, `.claude/audits/`, `.claude/deploy/` and `.githooks/`. A commit there that touches `.claude/rules/`, `.claude/settings.json`, agents or skills is blocked: branch first. The global hooks update at `make link`, a project's own `.githooks/` at its next session start.
- **Invalid `gitflow.autopush` value**: anything but unset, `true` or `false` now pushes nothing, where it used to push. `bash ~/.claude/lib/gitflow.sh push-mode` prints `invalid` in that case; fix the value by hand. A project with committed `.githooks/` keeps its old hooks until a session start rewrites them: commit that refresh so other clones get it.
Also part of 3.0.0, each with its own section above: "Memory registries v2" (optional), "Auto memory off" and "Claude.ai-synced skills off" (check `claude --version` before pulling).