docs(doctrine): model-agnostic ceiling held by the router guard, finish/merge ask, ask prompts under auto, static rule limits

This commit is contained in:
bchanot committed 2026-11-02 18:45:59 +01:00
1 parent 536d39e811
commit 0bf46202de
3 files changed
+41 -25

No files matched your search

+8 -4
View File
@@ -61,13 +61,15 @@ code" wins. Repo-specific instructions override both.
changes unless a broader refactor is requested. State trade-offs.
- Sub-agents: one task each. Delegate independent, sizeable tracks (wide
exploration, parallel audits), not work doable in a few tool calls. Ceiling:
main on Fable writes no code past the `/hotfix` scope, it hands it to /feat
or /bugfix. Skill-mandated executors and gates (pinned executors, fresh
the main loop writes no code outside a skill run, whatever the model (the
model-router guard redirects it: enter the skill it names). Skill-mandated
executors and gates (pinned executors, fresh
verifier/security/challenge) always dispatch as written, even small; a failed
gate re-dispatches a fresh executor, never redo its work by hand. A brief
never authorizes a sub-agent to run a destructive tool (Security →
Destructive tools & data loss) or to route around a guardrail: a refused
command is reported with its rule, never rerun through a wrapper, alias, env
command is reported with its rule (a guard redirect naming a skill is
followed instead), never rerun through a wrapper, alias, env
file or other shell. Hermetic tests run through `make test [suite=…]` only.
- Ask rather than guess. A choice visible in the result (placement,
wording, order, behavior), a name that becomes public (command, flag,
@@ -160,7 +162,9 @@ and lands in place; a standalone memory task branches `chore/*`).
Branch, merge and delete only via the lib: `bash ~/.claude/lib/gitflow.sh
start <type> <name>` · `finish` · `delete <br>`. `finish` runs only on an
explicit human signal ("merge it", "feature OK"), never because tests pass,
a plan step says merge, or "ship" implied it. Assistance flows (`/feat`
a plan step says merge, or "ship" implied it. Ask rules prompt every
`gitflow.sh finish` and `git merge` (a `git -C <dir> merge` is not covered).
Assistance flows (`/feat`
`/bugfix` `/hotfix`) and the standalone memory/doc skills auto-branch on a
protected base but commit in place on a working branch, never finishing
(one exception, BDR-068: `/capitalize` and `/close` auto-finish the
+20 -5
View File
@@ -71,8 +71,8 @@ commands, settings, secrets, maintenance.
Doctrine: the main loop runs on the `opus` session model; the model-router rows
lift it to Fable for main-loop reflection ONLY: brainstorm, plan, contract,
audit judgment, loop decisions. On Fable it writes no code past the `/hotfix`
scope; the fresh gates run as dispatched agents on the `audit` row. The
audit judgment, loop decisions. The main loop writes no code outside a skill run (the router's guard
redirects it to a skill); the fresh gates run as dispatched agents on the `audit` row. The
Fable/Opus model floor is enforced by a blocking gate (`lib/model-gate.md`) at
the entry of the 17 reflection skills (the orchestrators, `/analyze`,
`/guardrails` and `/a11y`): the skill calls the model-router `route` tool and
@@ -403,9 +403,24 @@ The permission gate is now one `autoMode.soft_deny` entry covering the
outward-facing verbs (`21st publish*`, `submit`, `edit`, `delete`,
`remove-from-catalog`, `profile set|upload`), because publishing a component
puts it on a public listing under your account. That tier rather than `ask`:
under `defaultMode: auto` (this config's default) `ask` rules were observed
auto-approving with no prompt raised (LRN-153), so an `ask` entry would have
declared an intent without gating anything.
an ask prompt can be clicked through by reflex, and the soft_deny also covers
scripted forms.
### Static rule limits
`ask` rules raise a permission prompt under `defaultMode: auto` (headless
bench `.claude/tasks/plans/2026-11-02-phase2-bench/`, confirmed interactively
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
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
unrewritten, so the native rules judge it as typed.
### Higgsfield CLI
+13 -16
View File
@@ -77,18 +77,18 @@ machine. Project facts (this repo's deploy target, its secrets, its data)
belong in that project's `.claude/settings.local.json`. A global block naming
one repo feeds the classifier false facts in all the others.
### `ask` is not a prompt under auto mode
### `ask` prompts under auto mode
Verified in-session (LRN-146, re-verified on 2.1.273 on 2026-09-16 with a
`node -e` probe matching an `ask` rule): with `defaultMode: auto`, Bash rules
in `permissions.ask` were auto-approved and raised no prompt. The auto-mode
docs claim the opposite for "content-scoped" rules such as `Bash(git push *)`;
the observed behavior wins until a probe shows a prompt. `deny` is the only
tier the classifier cannot lift.
Measured 2026-11-02 (headless bench under `defaultMode: auto`, then one
interactive session): a Bash command matching `permissions.ask` raises a
permission request; in `-p` it is refused. LRN-155 (2026-09-16, a `node -e`
probe on 2.1.273: `ask` rules auto-approved interactively) is not
reproduced; its cause is not established. `deny` is the only tier the
classifier cannot lift.
So for a destructive command you want gated but still reachable, `ask` is the
wrong tier. Use `autoMode.soft_deny`: blocked until the user's intent clears
it. Keep `deny` for what must never run at all.
`ask` gates a command you approve per call; `soft_deny` gates one the
classifier clears from your request. Keep `deny` for what must never run at
all.
### Picking a tier
@@ -98,11 +98,9 @@ it. Keep `deny` for what must never run at all.
| Never runs, and a pattern cannot express it (a read then a send, a prod target) | `autoMode.hard_deny` |
| Runs when the user asks for it, blocked otherwise | `autoMode.soft_deny` |
| Runs freely when a condition holds that only the classifier can judge (a local dev container, a package declared in the lockfile) | `autoMode.allow` |
| Runs after you click, every time | `permissions.ask` |
| Runs freely | `permissions.allow`, or nothing |
`permissions.ask` is not on this list on purpose. Under `defaultMode: auto` it
gates nothing.
`autoMode.allow` is the exception tier: inside the classifier an `allow` entry
overrides a matching `soft_deny`, built-in or yours, so word it as narrowly as
the condition allows. It is also the only tier that can open an interpreter:
@@ -130,8 +128,7 @@ no separate setting for this.
- `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.
- Under `defaultMode: auto`, `ask` does not raise a prompt (see above). A destructive
command belongs in `deny` or in `autoMode.soft_deny`, not in `ask`.
- Under `defaultMode: auto`, `ask` prompts; a command that must never run belongs in `deny`.
## Data-loss guardrails (BDR-095)
@@ -146,7 +143,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`. |
| Pushing in manual-push mode (`gitflow.autopush false`, or any invalid value) | `hooks/push-guard.sh` (PreToolUse) + `autoMode.soft_deny` | `ask` is inert under auto mode. 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`. |
| 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. |