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:
1 parent
536d39e811
commit
0bf46202de
3 files changed
+41
-25
No files matched your search
+8
-4
@@ -61,13 +61,15 @@ code" wins. Repo-specific instructions override both.
|
|||||||
changes unless a broader refactor is requested. State trade-offs.
|
changes unless a broader refactor is requested. State trade-offs.
|
||||||
- Sub-agents: one task each. Delegate independent, sizeable tracks (wide
|
- Sub-agents: one task each. Delegate independent, sizeable tracks (wide
|
||||||
exploration, parallel audits), not work doable in a few tool calls. Ceiling:
|
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
|
the main loop writes no code outside a skill run, whatever the model (the
|
||||||
or /bugfix. Skill-mandated executors and gates (pinned executors, fresh
|
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
|
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
|
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 →
|
never authorizes a sub-agent to run a destructive tool (Security →
|
||||||
Destructive tools & data loss) or to route around a guardrail: a refused
|
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.
|
file or other shell. Hermetic tests run through `make test [suite=…]` only.
|
||||||
- Ask rather than guess. A choice visible in the result (placement,
|
- Ask rather than guess. A choice visible in the result (placement,
|
||||||
wording, order, behavior), a name that becomes public (command, flag,
|
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
|
Branch, merge and delete only via the lib: `bash ~/.claude/lib/gitflow.sh
|
||||||
start <type> <name>` · `finish` · `delete <br>`. `finish` runs only on an
|
start <type> <name>` · `finish` · `delete <br>`. `finish` runs only on an
|
||||||
explicit human signal ("merge it", "feature OK"), never because tests pass,
|
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
|
`/bugfix` `/hotfix`) and the standalone memory/doc skills auto-branch on a
|
||||||
protected base but commit in place on a working branch, never finishing
|
protected base but commit in place on a working branch, never finishing
|
||||||
(one exception, BDR-068: `/capitalize` and `/close` auto-finish the
|
(one exception, BDR-068: `/capitalize` and `/close` auto-finish the
|
||||||
|
|||||||
@@ -71,8 +71,8 @@ commands, settings, secrets, maintenance.
|
|||||||
|
|
||||||
Doctrine: the main loop runs on the `opus` session model; the model-router rows
|
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,
|
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`
|
audit judgment, loop decisions. The main loop writes no code outside a skill run (the router's guard
|
||||||
scope; the fresh gates run as dispatched agents on the `audit` row. The
|
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
|
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`,
|
the entry of the 17 reflection skills (the orchestrators, `/analyze`,
|
||||||
`/guardrails` and `/a11y`): the skill calls the model-router `route` tool and
|
`/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`,
|
outward-facing verbs (`21st publish*`, `submit`, `edit`, `delete`,
|
||||||
`remove-from-catalog`, `profile set|upload`), because publishing a component
|
`remove-from-catalog`, `profile set|upload`), because publishing a component
|
||||||
puts it on a public listing under your account. That tier rather than `ask`:
|
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
|
an ask prompt can be clicked through by reflex, and the soft_deny also covers
|
||||||
auto-approving with no prompt raised (LRN-153), so an `ask` entry would have
|
scripted forms.
|
||||||
declared an intent without gating anything.
|
|
||||||
|
### 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
|
### Higgsfield CLI
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
belong in that project's `.claude/settings.local.json`. A global block naming
|
||||||
one repo feeds the classifier false facts in all the others.
|
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
|
Measured 2026-11-02 (headless bench under `defaultMode: auto`, then one
|
||||||
`node -e` probe matching an `ask` rule): with `defaultMode: auto`, Bash rules
|
interactive session): a Bash command matching `permissions.ask` raises a
|
||||||
in `permissions.ask` were auto-approved and raised no prompt. The auto-mode
|
permission request; in `-p` it is refused. LRN-155 (2026-09-16, a `node -e`
|
||||||
docs claim the opposite for "content-scoped" rules such as `Bash(git push *)`;
|
probe on 2.1.273: `ask` rules auto-approved interactively) is not
|
||||||
the observed behavior wins until a probe shows a prompt. `deny` is the only
|
reproduced; its cause is not established. `deny` is the only tier the
|
||||||
tier the classifier cannot lift.
|
classifier cannot lift.
|
||||||
|
|
||||||
So for a destructive command you want gated but still reachable, `ask` is the
|
`ask` gates a command you approve per call; `soft_deny` gates one the
|
||||||
wrong tier. Use `autoMode.soft_deny`: blocked until the user's intent clears
|
classifier clears from your request. Keep `deny` for what must never run at
|
||||||
it. Keep `deny` for what must never run at all.
|
all.
|
||||||
|
|
||||||
### Picking a tier
|
### 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` |
|
| 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 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 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 |
|
| 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
|
`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
|
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:
|
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.
|
- `disableBypassPermissionsMode: "disable"` prevents switching to bypass mode mid-session.
|
||||||
- Prefer `autoMode.soft_deny` over `allow` for anything touching external systems.
|
- 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.
|
- `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
|
- Under `defaultMode: auto`, `ask` prompts; a command that must never run belongs in `deny`.
|
||||||
command belongs in `deny` or in `autoMode.soft_deny`, not in `ask`.
|
|
||||||
|
|
||||||
## Data-loss guardrails (BDR-095)
|
## 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. |
|
| 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. |
|
| 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`. |
|
| 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. |
|
| 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. |
|
| `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