docks-kit 0.22.6 → 0.22.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -42,9 +42,9 @@ launcher can fall back to Bun source.
42
42
  | `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags, resolved model catalog) |
43
43
  | `cli/src/engine-native/kitDb.ts` | Only opener of the SQLite store `~/.docks-kit/kit.db`: append-only migrations, one-time `state.json` import, TTL cache |
44
44
  | `cli/src/engine-native/liveModels.ts` | Live model list per enabled harness (Anthropic API via Claude Code login, Codex model cache, `omp models --json`) merged over `SoT/models.json` |
45
- | `.oxlintrc.json` / `.oxfmtrc.json` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and code format scope |
45
+ | `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
46
46
  | `cli/test/fixtures/` | Golden fixtures: `home-fresh`, `home-drift`, `home-invalid-json`, `codex-toml`, `statusline` |
47
- | `cli/` | Effect 4 RC CLI + bundled docs topics |
47
+ | `cli/` | Effect 4 CLI + bundled docs topics |
48
48
  | `SoT/models.json` | Curated Claude and Codex model overlay: aliases and notes always apply; id rows are the fallback when a harness live list is unavailable |
49
49
  | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
50
50
  | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
@@ -78,8 +78,8 @@ omp SoT notes:
78
78
  - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
79
79
  - `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`. Under a named omp profile (`OMP_PROFILE` or `PI_PROFILE`), it deploys to `<profile agentDir>/intercom/config.json`, because omp exports `PI_CODING_AGENT_DIR` as the profile agent directory.
80
80
  - `ompFileDeploy.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards and merges `bash.patterns`.
81
- - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. By the 0.20.9 decision, omp does not prompt for other file removal: a non-denied `rm`, `git rm`, `git worktree remove`, `gio trash`, and `docks-kit scratch remove` run without a prompt. The prompts left are the history-loss commands: `git clean`, `git reset --hard`, and every `git push` form that could force. A `$` or a backtick anywhere after `git push` in the same command is a deny, not a prompt (0.22.5, #120). A variable can expand to a `+` refspec or `--force`, and the matcher reads the text before the shell expands it. The agent reads the refusal and writes the ref literally, so no person is asked. The two rules are `*git push *$*` and ``*git push *`*``. Their leading `*` keeps a shell keyword such as `do`, a wrapper such as `env`, or a path before `git` from hiding the push. omp also prompts before a git command that skips the repository's hooks (#111): a word after `git` that starts with `--no-v` (git accepts each unique prefix of `--no-verify`, and `git am` accepts `--no-v`), a `git commit` or `git am` short-option cluster that can hold `-n`, `core.hooksPath` or `core.hookspath` after `git`, and a line that names `GIT_CONFIG_COUNT` or `GIT_CONFIG_PARAMETERS`. Each of these rules starts with `*`, so a word before `git`, such as `HUSKY=0`, `env`, or `/usr/bin/`, does not hide the command; `cli/docs/command-guards.md` lists the gaps. omp never applies an allow rule to a command that holds a `$` that the shell expands, so no kit exception can exempt a branch delete in a loop; `SoT/.omp/AGENTS.md` tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. The list order is deny, then prompts, then `trash *`. omp takes the first match. `ompYaml.ts mergeBashPatterns, exception-aware rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit exception (a kit allow listed before the first kit prompt; the kit currently ships none), kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 18.11.1's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
82
- - `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value. The same pass removes each `bash.patterns` rule listed in `OMP_RETIRED_BASH_RULES`: the 39 file-removal rules retired in 0.20.9, and the four `git push` prompts for a `$` or backtick word that 0.22.5 replaced with denies. It compares with the merge's kit-rule normalization (approval case-folded, `match` whitespace collapsed), so a user rule with a different `match` or `approval` survives.
81
+ - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. A `$` or a backtick anywhere after `git push` in the same command is a deny, not a prompt (0.22.5, #120). A variable can expand to a `+` refspec or `--force`, and the matcher reads the text before the shell expands it. The agent reads the refusal and writes the ref literally, so no person is asked. The two rules are `*git push *$*` and ``*git push *`*``. Their leading `*` keeps a shell keyword such as `do`, a wrapper such as `env`, or a path before `git` from hiding the push. By owner decision (0.22.8, #126), the kit ships no omp prompt rule: `bash.patterns` holds only the denies plus the `trash *` allow, so every command that no deny matches runs without a question, in subagents too. Since 0.20.9 this run-without-question behavior covers a non-denied `rm`, `git rm`, `git worktree remove`, `gio trash`, and `docks-kit scratch remove`. Since 0.22.8 it also covers `git clean`, `git reset --hard`, a hook skip, and every `git push` that no deny matches. The force-push denies match only `git push --force` or `-f` directly before `origin main` or `origin master`, so another spelling, such as `git push origin main --force`, runs. A prompt rule that the user adds survives sync and still asks. `SoT/.omp/AGENTS.md` carries the agent rules for these commands, and it tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. Claude Code `permissions.ask` and Codex `docks.rules` keep their ask tiers. The list order is deny, then `trash *`. omp takes the first match. `ompYaml.ts mergeBashPatterns, grouped rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 18.11.1's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
82
+ - `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value. The same pass removes each `bash.patterns` rule listed in `OMP_RETIRED_BASH_RULES`: the 39 file-removal rules retired in 0.20.9, the four `git push` prompts for a `$` or backtick word that 0.22.5 replaced with denies, and the 492 prompt rules retired in 0.22.8 (`RETIRED_PROMPT_MATCHES`). It compares with the merge's kit-rule normalization (approval case-folded, `match` whitespace collapsed), so a user rule with a different `match` or `approval` survives.
83
83
  - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` remains `anthropic/claude-fable-5-1:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
84
84
  - `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.1-sol:high`. `task.maxEffort` is `xhigh`: a caller `effort: hi` outranks the role's `:high` suffix and maps to the top of the model ladder, so the cap keeps `hi` at `xhigh` instead of `max`. `advisor` is `anthropic/claude-opus-5-5:medium` with an empty fallback chain, because a GPT-6 Sol advisor looped on repeated reads under an Opus 5.5 session. Never put any GPT model (`openai-codex/gpt-*`, including GPT-6.1 Sol and GPT-6 Astra) in the advisor role or chain; Astra also costs too much for this role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-sol:xhigh` with `anthropic/claude-opus-5-5:xhigh` as its retry fallback, and all four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant. The `SoT/toolchain.json` omp floor is 18.4.4, the oldest release the kit tested with `gpt-6.1-sol`. That release lists and serves the model through the `openai-codex` provider. `cli/docs/omp-models.md` records the checks.
85
85
  - The seven Opus 5.5 roles (`default`, `slow`, `plan`, `designer`, `vision`, `task`, `advisor`) and the `smol`, `tiny`, `commit`, and `reviewer` retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-29 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. Opus 5.5 max has the highest index in that topic, at 58. AA has measured speed and latency for Opus 5.5 max and every GPT-6.1 Sol level; GPT-6 Luna medium is the only unmeasured speed and latency row.
@@ -92,7 +92,7 @@ omp SoT notes:
92
92
  - Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
93
93
  - Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`: directories 0700, files 0600, `package.json` `version` set to the kit version, stale files removed, no backups because the directory is kit-owned). `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>` unless the `omp plugin list --json` npm row `docks-kit-omp` already has a `path` that resolves to that directory; `--skip-plugin-refresh` does not skip the link. The plugin extension registers `scratch_new`, `scratch_remove`, and `tidy_report`, adds a reminder after each bash command that created a resource, checks at session stop that those resources are gone, and at a main-session start claims `~/.cache/docks-kit/tidy.stamp.claim` and runs `docks-kit tidy --apply` in the background at most once per 12 hours. Every extension subprocess runs without a shell. The plugin also ships the `workspace-hygiene` skill and the `/cleanup` command. The plugin, the deployed rules, and the sweep call `docks-kit scratch` and `docks-kit tidy`, so a checkout sync must not run before the global `docks-kit` carries those commands.
94
94
  - `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
95
- - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp prompt rules, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH or a provider CLI such as `wrangler`, `vercel`, `kubectl`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
95
+ - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp agent prompt, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH or a provider CLI such as `wrangler`, `vercel`, `kubectl`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
96
96
  - The omp CLI is upstream-owned. It updates through `omp update`, or through the external manager that owns the install, such as Tern or Nix. `omp update` refuses to run on an install that an external manager owns. Sync never installs or upgrades the CLI.
97
97
  - `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session. The overlay sets the 16 roles in `ompOverlay.ts ROLE_ORDER`, `judge` and `memory` included, to one free model, empties the 13 retry chains in `FALLBACK_ORDER`, and empties the chains keyed by the free model (bare, `off`, and every `THINKING_LADDER` level). Every other deployed chain stays as deployed. In particular, `modelRoles.web` and `retry.fallbackChains.web` keep the deployed web-search provider order. Thus a web search that falls through the `web/*` providers can reach the paid `openai-codex/gpt-6-luna` entry. It renders the overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600). `ompOverlay.ts overlayFileName` gives each distinct model-and-level combination its own file, and the digest covers the selector and both levels. omp can re-read the overlay during a live session, so a second launcher with another model or level must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again.
98
98
  - The launcher enforces the free model before omp starts. `omp.ts rejectedForwardedFlag` rejects a forwarded `--config`, `--model`, `--smol`, `--slow`, `--plan`, `--models`, `--provider`, `--prewalk-into`, or `--plan-yolo-into`, in both forms and also after a `--`, with exit 2 and a message that names the recoveries. `ompOverlay.ts buildOmpArgs` starts omp as `omp launch --config <overlay> --model <selector>[:<level>] [args...]`, so every forwarded word is message text, no omp subcommand runs through the launcher, and `--continue` or `--resume` keeps the free model. `ompOverlay.ts ompChildEnvironment` sets `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values, and appends the overlay to `PI_CONFIG_FILES` so an `omp` that the bash tool of the session starts loads it too. The launcher prints one warning for each exported model variable that it replaces. In-session selection (`Alt+M`, `Alt+P`, `/switch`, `/model`, `/modelpreset`, `/resume`, a seance subagent), the `web` role, the model-kind roles `image`, `speech`, and `dictation`, and extensions and hooks stay outside the launcher. An `Alt+M` assignment of `default` writes `modelRoles.default` to the deployed `~/.omp/agent/config.yml`. `cli/docs/omp-models.md` lists these paths.
@@ -106,8 +106,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
106
106
  - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
107
107
  - **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `syncDispatch.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, and a missing `SoT/toolchain.json` pin stay warn-only with exit 0; an unavailable plugin inventory warns without a ledger row and falls back to the full refresh, whose failed commands are recorded. `ompMarketplace.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
108
108
  - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
109
- - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.115` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.3` (inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`; 5.0.3 fixes GHSA-qxg6-89mg-rqv8 and GHSA-xp26-3454-mjgp, and is past the 5.x patch point for GHSA-82fw-gwwq-j7x9, fixed in 5.0.0-rc.2). The lockfile resolves the `vite` peer of `@vitest/mocker` to 7.3.7, which fixes the launch-editor and `server.fs.allow` advisories up to 7.3.6. `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
110
- - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
109
+ - **Effect 4 CLI stack.** The CLI pins `effect@4.1.2` (including `effect/cli`), `@effect/platform-bun@4.1.2` (`BunServices.layer`, `BunRuntime.runMain`), and `@effect/platform-node-shared@4.1.2`. `effect/cli`, `effect/Terminal`, `BunRuntime`, and `BunServices` carry `@stability unstable`, so a minor Effect release can break them; 4.1.0 added a required `Terminal.size`. Tests run on `vitest@5.1.0`, a plain devDependency. No GitHub advisory affects vitest 5.1.0: 5.0.3 fixed GHSA-qxg6-89mg-rqv8 and GHSA-xp26-3454-mjgp, and 5.0.0-rc.2 fixed GHSA-82fw-gwwq-j7x9. The lockfile resolves the `vite` peer to 7.3.7, which fixes the launch-editor and `server.fs.allow` advisories up to 7.3.6 and has no open advisory. `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
110
+ - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
111
111
  - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
112
112
  - **Per-machine harness selection.** The SQLite store `~/.docks-kit/kit.db` drives a flag-less sync. A missing selection selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection. `docks-kit harnesses` is the only command that writes the `harness_selection` table. With no stored selection, its picker pre-ticks all four harnesses, `omp` included, so a new machine opts out of omp instead of opting in; nothing changes until the picker saves. The same store holds the independent `omp_session` table, which only `docks-kit omp` writes, and a TTL cache (`cache_entry`) for the live Anthropic model list and `toolchain outdated` lookups. `kitDb.ts withKitDb` is the only opener: it runs the append-only `MIGRATIONS`, imports a legacy `state.json` once and renames it to `state.json.migrated`, and refuses a store from a newer schema. Cache rows carry the kit version as fingerprint, so a new release refetches them.
113
113
  - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claudeRemovals.ts REMOVED_MANIFEST, baseline removal inventory`), a curated list of unambiguous kit-owned artifacts that `claudeRemovals.ts syncRemovals, baseline artifact prune` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts. Codex `config.toml` merges at table granularity: a table the SoT declares (`[features]`, `[sandbox_workspace_write]`, `[tui]`, ...) is replaced wholesale, so user keys inside it are dropped. The prior file stays in `config.toml.bak`, and user-only top-level keys and tables survive.
@@ -129,11 +129,11 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
129
129
 
130
130
  - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
131
131
  - Treat external plugin marketplaces and installer downloads as untrusted input. Prefer download-then-run over `curl … | bash` so a truncated stream cannot execute a partial script.
132
- - **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Moving the Effect release is therefore one lockstep commit: set `effect`, `@effect/platform-bun`, `@effect/platform-node-shared`, and `@effect/vitest` to the same version together, then run `bun run smoke:package`; the guard reports `unsatisfied` while one of them lags. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
132
+ - **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Moving the Effect release is therefore one lockstep commit: set `effect`, `@effect/platform-bun`, and `@effect/platform-node-shared` to the same version together, then run `bun run smoke:package`. The offline guard fails when a lag breaks a declared range. Its peer-range check fails when the installed `effect` is outside a non-optional peer range of the runtime closure. Its nested-copy check fails when `@effect/platform-node-shared` lags. A lagging `@effect/platform-bun` can keep every declared range satisfied (4.1.1 accepts `@effect/platform-node-shared` `^4.1.1`), so only the lockstep commit keeps it in step. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
133
133
  - **One exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer.
134
134
  ## Testing
135
135
 
136
- Run `bun run check` before and after each change: oxlint, `oxfmt --check`, `bun check`, unit tests, and both golden suites. Scripts: `lint`, `format:check`, `typecheck`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on push and pull request with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `oxfmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
136
+ Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on push and pull request with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
137
137
 
138
138
  Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
139
139
 
package/README.md CHANGED
@@ -59,15 +59,18 @@ docks-kit docs [topic] self-documentation (12 topics)
59
59
  --help --version --wizard --completions built-in
60
60
  ```
61
61
 
62
- The CLI is a typed Effect 4 RC front-end on Bun; all mutation runs through
62
+ The CLI is a typed Effect 4 front-end on Bun; all mutation runs through
63
63
  EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
64
64
  dry-run output, mutation snapshots, and argv logs. Its dependency graph is
65
- `effect@4.0.0-rc.115` (including `effect/unstable/cli`),
66
- `@effect/platform-bun@4.0.0-rc.115` (`BunServices.layer` and
67
- `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.115`, and `vitest@5.0.3`
68
- (inside the `@effect/vitest` peer range `>=5.0.0 <6.0.0`). `@effect/cli` and
69
- `@effect/platform` are removed: neither has a 4.x release, the CLI API moved
70
- into core, and the standalone platform package was unused here.
65
+ `effect@4.1.2` (including `effect/cli`), `@effect/platform-bun@4.1.2`
66
+ (`BunServices.layer` and `BunRuntime.runMain`), and
67
+ `@effect/platform-node-shared@4.1.2`. Tests run on `vitest@5.1.0`.
68
+ `bun run lint:effect` checks the Effect rules through `@effect/tsgo`. The
69
+ same package can run as the editor's TypeScript language server
70
+ (`node_modules/.bin/effect-tsgo tsc --lsp --stdio`).
71
+ `@effect/cli` and `@effect/platform` are removed: neither has a 4.x release,
72
+ the CLI API moved into core, and the standalone platform package was unused
73
+ here.
71
74
 
72
75
  ### Key flags (`docks-kit sync`)
73
76
 
@@ -110,18 +113,16 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
110
113
  Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
111
114
  or Stop hook. If Bun cannot be resolved or bootstrapped, sync preserves a
112
115
  working legacy hook/statusline setup and reports that migration is deferred.
113
- - **Command guards** — omp, Claude Code, and Codex share one fail-closed
114
- policy for destructive shell commands; to remove, agents use the trash
116
+ - **Command guards** — omp, Claude Code, and Codex share one policy for
117
+ destructive shell commands; to remove, agents use the trash
115
118
  (`gio trash -- <path>`, or `trash <path>` on macOS); omp agents remove a
116
119
  temporary file or directory with `docks-kit scratch remove`. `rm` of the
117
120
  home directory or `/` and `HOME` reassignment are denied. omp also denies
118
- every recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`, and
119
- runs any other `rm` without a prompt. In omp, `git clean`,
120
- `git reset --hard`, any `git push` that could force, and the common forms
121
- of a git command that skips the repository's hooks (`--no-verify`,
122
- `git commit -n`, a `core.hooksPath` change) ask; Claude Code and
123
- Codex also ask before `find -delete`, a recursive `rm`, and every `git rm`.
124
- An omp subagent cannot answer an ask, so omp rejects it; a Codex ask can go
121
+ every recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`. The
122
+ kit ships no omp prompt rule, so omp runs every command that no deny
123
+ matches without a question, in subagents too. Claude Code and Codex ask
124
+ before a recursive `rm`, `find -delete`, every `git rm`, `git clean`,
125
+ `git reset --hard`, and any `git push` that could force; a Codex ask can go
125
126
  to its `auto_review` reviewer. Details, per-tool differences, and gaps:
126
127
  `docks-kit docs command-guards`.
127
128
  - **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
@@ -144,7 +145,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
144
145
  | `SoT/toolchain.json` | Verified-version floors |
145
146
  | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
146
147
  | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
147
- | `cli/` | docks-kit CLI (Effect 4 RC on Bun) + bundled docs topics |
148
+ | `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
148
149
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
149
150
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
150
151
  | `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
@@ -6,28 +6,39 @@ The short rule for agents: **to remove, use the trash**. Run
6
6
  temporary file or directory with `docks-kit scratch remove <path>` instead.
7
7
  To remove a path from the git index, run `git rm -- <path>`.
8
8
 
9
- The policy follows one principle: **fail closed**. A command is allowed only
10
- in a canonical form that is safe by construction. Every other form that could
11
- force, empty, or delete asks. Where omp's critical-command check acts, the
12
- form is denied instead. omp also denies a `$` or a backtick after `git push`,
9
+ Claude Code and Codex follow one principle: **fail closed**. A command is
10
+ allowed only in a canonical form that is safe by construction, and every other
11
+ form that could force, empty, or delete asks. omp keeps only the deny part of
12
+ that principle. Where omp's critical-command check acts, the form is denied
13
+ instead of asked. omp also denies a `$` or a backtick after `git push`,
13
14
  because the agent can always write the ref literally. A false positive in the
14
- ask tier is accepted. omp is
15
- the exception for file removal: by owner decision, omp runs any removal that
16
- it does not deny without a prompt. omp still asks before a removal that loses
17
- history: `git clean`, `git reset --hard`, and a force push. omp also asks
18
- before a git command that skips the repository's hooks.
19
-
20
- The policy sorts shell commands into three tiers:
15
+ ask tier is accepted.
16
+
17
+ omp is the exception: by owner decision (0.22.8, #126), the kit ships no omp
18
+ prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
19
+ allow. Under the kit's `tools.approvalMode: yolo`, omp runs every command
20
+ that no deny matches without a question, in the main session and in
21
+ subagents. This includes any `rm` that omp does not deny, `git clean`,
22
+ `git reset --hard`, a force push that no deny matches, and a git command
23
+ that skips the repository's hooks. A prompt rule that the user adds to
24
+ `~/.omp/agent/config.yml` survives sync and still asks; a subagent rejects
25
+ it. The deployed omp agent prompt forbids `--force`, `-f`, and their
26
+ abbreviations with `git push`, and it forbids each hook skip. It tells the
27
+ agent to use `ask` before a force push, and to ask the user before
28
+ `git clean` or `git reset --hard`.
29
+
30
+ The policy sorts shell commands into three tiers. omp uses two of them: deny
31
+ and allow.
21
32
 
22
33
  - **Deny**: the command never runs, and nobody can approve it in the session.
23
- - **Ask**: the command needs approval before it runs.
24
- - omp asks a person in the main session. omp runs subagents headless, so it
25
- rejects every ask in a subagent.
34
+ - **Ask**: the command needs approval before it runs. The kit ships no omp
35
+ rule in this tier.
26
36
  - Claude Code asks a person, even in auto mode.
27
37
  - Codex sends the prompt to the approvals reviewer in the kit's
28
38
  `config.toml`. That reviewer is `auto_review`, a reviewer subagent, so a
29
39
  Codex ask can be approved without a person.
30
- - **Allow**: the agent may run the command alone.
40
+ - **Allow**: the agent may run the command alone. In omp, a command that no
41
+ rule matches runs too. The table below calls this `run`.
31
42
 
32
43
  The omp `eval` tool stays unrestricted: `bash.patterns` does not gate a shell
33
44
  that `eval` starts.
@@ -43,21 +54,24 @@ that `eval` starts.
43
54
  | `git push --force` or `-f` to `origin main` or `origin master` | deny | deny | deny |
44
55
  | Recursive `rm` (`-r`, `-R`, `-rf`, `-fr`, `-rfv`, `-ri`, `-ir`, `-Ri`, `-iR`, `--recursive`, other listed clusters) | deny, also behind any prefix (`env`, `xargs`, `nice`, `find -exec`, `git rm -r`) | ask | ask (every `rm` asks) |
45
56
  | `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny | ask if recursive, else classifier | ask |
46
- | Any other `rm`: one file, several files, a glob, `-f` | allow | glob asks; the rest goes to the classifier | ask |
57
+ | Any other `rm`: one file, several files, a glob, `-f` | run | glob asks; the rest goes to the classifier | ask |
47
58
  | `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask | ask (every `find` asks) |
48
- | `git clean`, `git reset --hard` | ask | ask | ask |
49
- | `git push` that could force: see below | ask | ask | ask (every `git push` asks) |
59
+ | `git clean`, `git reset --hard` | run | ask | ask |
60
+ | `git push` that could force: see below | run, unless a deny above matches | ask | ask (every `git push` asks) |
50
61
  | A `$` or a backtick anywhere after `git push` in the same command | deny, also after a shell keyword, a wrapper, or a path before `git`: see below | ask for a word that starts with `$` or a backtick | ask (every `git push` asks) |
51
- | A git command that skips the repository's hooks: see below | ask | no rule; the classifier decides | ask for each `git push`, `git merge`, and `git rebase` that starts the command; no rule for `git commit`, `git am`, or `git pull` |
52
- | `git rm -- <path>`, `git worktree remove -- <path>` | allow | ask | ask |
53
- | `git worktree remove --force -- <path>` | allow; the omp prompt permits it once, after the commits are on the remote | ask | ask |
54
- | `docks-kit scratch remove <path>` | allow; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` | no rule | no rule |
55
- | Any other non-recursive `git rm` or `git worktree remove` | allow | ask | ask |
56
- | `gio trash -- <path>` | allow | allow | ask |
57
- | Any other `gio trash` | allow | ask with `--empty` or `--restore`; the rest goes to the classifier | ask |
62
+ | A git command that skips the repository's hooks: see below | run | no rule; the classifier decides | ask for each `git push`, `git merge`, and `git rebase` that starts the command; no rule for `git commit`, `git am`, or `git pull` |
63
+ | `git rm -- <path>`, `git worktree remove -- <path>` | run | ask | ask |
64
+ | `git worktree remove --force -- <path>` | run; the omp agent prompt permits it once, after the commits are on the remote | ask | ask |
65
+ | `docks-kit scratch remove <path>` | run; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` | no rule | no rule |
66
+ | Any other non-recursive `git rm` or `git worktree remove` | run | ask | ask |
67
+ | `gio trash -- <path>` | run | allow | ask |
68
+ | Any other `gio trash` | run | ask with `--empty` or `--restore`; the rest goes to the classifier | ask |
58
69
  | `trash <path>` (macOS) | allow | allow | allow |
59
70
 
60
- A `git push` asks when it holds any of these words:
71
+ In Claude Code, a `git push` asks when it holds any of these words. Codex
72
+ asks for every `git push`. omp runs each of these forms. Its force-push deny
73
+ matches only `git push --force` or `git push -f` directly before
74
+ `origin main` or `origin master`:
61
75
 
62
76
  - a `+` refspec;
63
77
  - any long option that starts with `--f`, such as `--force`,
@@ -66,12 +80,12 @@ A `git push` asks when it holds any of these words:
66
80
  - `-f`, or a short-option cluster that starts with two of git push's
67
81
  no-argument flags (`v`, `q`, `d`, `n`, `u`, `4`, `6`, `f`), such as `-vf`,
68
82
  `-vvf`, or `-uvfq`;
69
- - in Claude Code, a word that starts with `$`, a backtick, a quote, or a
70
- backslash. omp denies a `$` or a backtick anywhere after `git push`.
83
+ - a word that starts with `$`, a backtick, a quote, or a backslash. omp
84
+ denies a `$` or a backtick anywhere after `git push`.
71
85
 
72
86
  Each of these must begin a word: `feat/cache-vf` is a branch name, not an
73
- option. `--follow-tags` also asks. This is an accepted false positive, because
74
- it shares the `--f` prefix.
87
+ option. In Claude Code, `--follow-tags` also asks. This is an accepted false
88
+ positive, because it shares the `--f` prefix.
75
89
 
76
90
  A `$` or a backtick hides the ref until the shell expands it, so the matcher
77
91
  cannot tell `$b` from `+main` or `--force`. An unquoted value inside a word
@@ -81,7 +95,7 @@ also splits into more words: with `b="main --force"`, `HEAD:$b` becomes
81
95
  branch name.
82
96
 
83
97
  omp therefore denies a `$` or a backtick anywhere after `git push` in the same
84
- command, instead of asking. The agent reads a refusal such as
98
+ command. The agent reads a refusal such as
85
99
  `Blocked by bash pattern: *git push *$*`, writes the ref literally, and runs
86
100
  the push without a question. The omp agent prompt names the literal forms:
87
101
  `git push -u origin HEAD` for the current branch, and
@@ -91,54 +105,24 @@ such as `env`, or a path such as `/usr/bin/git` does not hide the push.
91
105
 
92
106
  ## Commands that skip the repository's hooks
93
107
 
94
- In omp, a command asks when it can skip the repository's hooks. Each of
95
- these rules also matches after a word before `git`, such as `X=1`, `env`,
96
- `timeout`, or a path like `/usr/bin/git`:
97
-
98
- - a word after `git` that starts with `--no-v`. Git accepts each unique
99
- prefix of `--no-verify`, and `git am` accepts the shortest, `--no-v`. This
100
- covers `git push`, `git commit`, `git merge`, `git pull`, `git rebase`, and
101
- `git am`, also after `git -C <dir>`;
102
- - `-n`, or a short-option cluster that starts with two no-argument options,
103
- in `git commit` or `git am`. Both read `-n` as `--no-verify`, also inside a
104
- cluster such as `-anm`. The no-argument options are `q`, `v`, `s`, `e`, `a`,
105
- `i`, `p`, `o`, `n`, and `z` for `git commit`, and `i`, `n`, `3`, `q`, `s`,
106
- `u`, `k`, `m`, `c`, and `r` for `git am`;
107
- - `core.hooksPath` or `core.hookspath` after `git`, as in `git -c`,
108
- `git --config-env`, or `git config`;
109
- - `GIT_CONFIG_COUNT` or `GIT_CONFIG_PARAMETERS` anywhere in the line, in any
110
- assignment form such as `=`, `+=`, or `export`. These variables can
111
- override any configuration key, `core.hooksPath` included, whatever its
112
- spelling. A line that sets them does not start with `git`, and a
113
- `GIT_CONFIG_PARAMETERS` entry keeps its inner quotes, as in
114
- `'core.hooksPath'='/dev/null'`.
115
-
116
- `git commit -m x`, `git commit -am x`, `git commit -sm x`, and
117
- `git commit -mn x` (the message `n`) run without a prompt. These forms ask as
118
- accepted false positives:
119
-
120
- - another option that starts with `--no-v`, such as `--no-verbose`,
121
- `--no-verify-signatures`, or `git send-email --no-validate`;
122
- - a cluster of two no-argument options without `n`, such as
123
- `git commit -aqm x`;
124
- - a read such as `git config --get core.hooksPath`. To read the hooks
125
- directory without a prompt, run `git rev-parse --git-path hooks`;
126
- - message or search text that holds ` -n`, a two-letter cluster, or `--no-v`,
127
- such as `git commit -m "use head -n 5"` or `git grep -- --no-verify`. Write
128
- such a message with `git commit -F <file>`;
129
- - a line with a later command, because omp tests the whole line:
130
- `git commit -m x && git log -n 1` asks. Run the commit as its own command.
108
+ A git command can skip the repository's hooks, for example with
109
+ `--no-verify`, `git commit -n`, `git am -n`, or a `core.hooksPath` change.
110
+ The kit ships no omp rule for these commands, so omp runs them without a
111
+ question. The deployed omp agent prompt forbids each hook skip. Claude Code
112
+ has no rule either, so its classifier decides. Codex asks for each
113
+ `git push`, `git merge`, and `git rebase` that starts the command. Codex has
114
+ no rule for `git commit`, `git am`, or `git pull`.
131
115
 
132
116
  ## Why the tools differ
133
117
 
134
118
  | Topic | omp | Claude Code | Codex |
135
119
  | --- | --- | --- | --- |
136
120
  | Rule order | First match wins | Deny, then ask, then allow, whatever the order | Strictest matching rule wins |
137
- | Exception for one form | An allow before a broader prompt works; the kit ships no such exception now | An allow never beats a matching ask, so every `git rm` asks | An allow never beats a matching prompt, so every `gio trash` asks |
121
+ | Exception for one form | The kit ships no omp prompt rule, so it needs no exception | An allow never beats a matching ask, so every `git rm` asks | An allow never beats a matching prompt, so every `gio trash` asks |
138
122
  | Pattern | Glob on the whole line and on each quote-stripped segment; `*` crosses spaces; no literal `*` | Glob on each subcommand as written, quotes included; `\*` is a literal `*` | Exact argv tokens from the start, with alternatives |
139
123
  | `rm` by path (`/bin/rm`) | Matched by `*/rm` forms | Matched by `*/rm` forms | Resolved to the `rm` rules |
140
124
  | Leading assignment `X=1 cmd` | Part of the line | Stripped before deny and ask rules | A script with it is not split |
141
- | What an ask means | A person in the main session; rejected in a subagent | A person | The `auto_review` reviewer subagent |
125
+ | What an ask means | The kit ships no ask; a user prompt rule asks a person in the main session, and a subagent rejects it | A person | The `auto_review` reviewer subagent |
142
126
  | Critical-command check | Turns a prompt into an allow under yolo, so the kit denies those shapes | Asks or denies for an `rm` of a critical path | Prompts for a forced `rm` that no rule matches |
143
127
 
144
128
  ## How an agent removes files
@@ -212,11 +196,12 @@ the home directory, and no glob can express "inside the temporary directory".
212
196
  - **omp**:
213
197
  - The rules are ordered, and the first match wins.
214
198
  - `*` matches any text, spaces included, and no escape spells a literal `*`.
215
- - Deny and prompt rules test the whole line and each segment between `;`,
216
- `&&`, `|`, and similar operators, with quotes and escapes removed. So
199
+ - Deny rules test the whole line and each segment between `;`, `&&`, `|`,
200
+ and similar operators, with quotes and escapes removed. So
217
201
  `rm -rf "$HOME"` matches `rm * $HOME`.
218
202
  - Allow rules apply only to a simple command.
219
- - The kit lists rules as deny, then prompts, then the `trash *` allow.
203
+ - The kit ships no prompt rule. It lists rules as deny, then the `trash *`
204
+ allow.
220
205
  - **Claude Code**:
221
206
  - Deny beats ask, and ask beats allow, whatever the order.
222
207
  - The rules match the command text as written, quotes included, so the kit
@@ -252,12 +237,6 @@ the home directory, and no glob can express "inside the temporary directory".
252
237
  `git commit -m "rm -f /tmp/x"`. The `git push` deny matches text that names
253
238
  `git push` before a `$`, such as `git commit -m "git push $b fails"`. Write
254
239
  such a message with `git commit -F`.
255
- - **omp, critical patterns in a line**: a line that holds one of omp's other
256
- critical patterns turns any matching prompt rule on that line into an
257
- allow. This applies to a compound line, such as one with `curl ... | sh`,
258
- and to message text: `git commit -n -m "fix reboot loop"` runs, because
259
- `reboot`, `shutdown`, `halt`, `mkfs`, `cryptsetup`, and `init 0` are
260
- critical words.
261
240
  - **omp, prefixed `rm`**: the kit denies a recursive `rm` behind any prefix,
262
241
  such as `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, or
263
242
  `git rm -r dir`. A `* rm ` rule also matches text, so a line such as
@@ -274,35 +253,21 @@ the home directory, and no glob can express "inside the temporary directory".
274
253
  `remote.<name>.push` makes a plain `git push` force. No rule sees git
275
254
  configuration. `git push --delete` and `git push --prune` remove remote
276
255
  branches without force; they ask only in Codex.
277
- - **omp, force push after a prefix**: the force-push deny and prompt rules
278
- start with `git push`, not `*`. So a force push after a shell keyword, a
279
- wrapper, or a path runs without a check, such as
256
+ - **omp, force push to `main` in another spelling**: the force-push deny
257
+ rules match only `git push --force` or `git push -f`, then
258
+ `origin main` or `origin master`. Every other force push to `main` runs
259
+ without a question, such as `git push origin main --force`,
260
+ `git push -vf origin main`, `git push --force-with-lease origin main`,
261
+ `git push origin +main`, `git push -f origin HEAD:main`, or
262
+ `git push --mirror origin`. Until 0.22.8 these forms asked.
263
+ - **omp, force push after a prefix**: the force-push deny rules start with
264
+ `git push`, not `*`. So a force push to `origin main` after a shell keyword,
265
+ a wrapper, or a path runs without a check, such as
280
266
  `for r in a; do git push --force origin main; done`,
281
267
  `env git push --force origin main`, or `/usr/bin/git push --force origin main`.
282
268
  - **`git -C`**: no tool matches a git subcommand that does not follow `git`
283
- directly, such as `git -C . push --force` or `git -C . push origin $b`. omp
284
- also lets `git -C . commit -n` run without a prompt. In omp, the
285
- `--no-verify` and `core.hooksPath` forms still ask after `git -C`.
286
- - **omp, `core.hooksPath` spelling**: git reads section and variable names
287
- without case, but omp matches with case. A key in another case, such as
288
- `CORE.HOOKSPATH` or `Core.HooksPath`, after `git -c`, `git --config-env`, or
289
- `git config` runs without a prompt.
290
- - **omp, configuration files**: a configuration file can set
291
- `core.hooksPath` without a rule seeing the key. This includes a file named
292
- through `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_SYSTEM`, `XDG_CONFIG_HOME`,
293
- `include.path`, or `includeIf`, and a direct edit of `.git/config`. The kit
294
- does not ask for these variables, because test scripts set
295
- `GIT_CONFIG_GLOBAL=/dev/null` routinely.
296
- - **omp on Windows, variable names**: Windows reads variable names without
297
- case, so a name such as `git_config_count` also overrides configuration and
298
- runs without a prompt.
299
- - **omp, git aliases**: an alias for `commit` or `am`, such as `git ci -n` or
300
- `git -c alias.ci=commit ci -n`, runs without a prompt.
301
- - **omp, other hook skips**: no rule covers a hook-manager switch, such as
302
- `HUSKY=0`, `SKIP=...`, or `LEFTHOOK=0`, or a change to the files in the
303
- hooks directory. `git commit --no-post-rewrite` also runs: the
304
- `post-rewrite` hook runs after the commit and cannot stop it. The deployed
305
- omp prompt forbids each hook skip.
269
+ directly, such as `git -C . push --force origin main` or
270
+ `git -C . push origin $b`.
306
271
  - **Claude Code, `HOME=` before a command**: Claude Code matches deny rules
307
272
  past a leading assignment. So `HOME=/tmp/x cmd` reaches the classifier.
308
273
  `export HOME=...`, `env HOME=...`, a bare `HOME=...` line, and any `rm` of
@@ -341,19 +306,18 @@ prompt. In Claude Code, any form with `--empty` or `--restore` asks.
341
306
  1. kit deny;
342
307
  2. user deny;
343
308
  3. user prompt;
344
- 4. kit allow exceptions (the kit allows listed before the first kit
345
- prompt; the kit currently ships none);
346
- 5. kit prompt;
347
- 6. the other user rules;
348
- 7. kit allow.
309
+ 4. kit prompt (the kit ships none since 0.22.8);
310
+ 5. the other user rules;
311
+ 6. kit allow.
349
312
  - A user deny or prompt thus precedes every kit allow, and no allow can
350
313
  loosen a deny or a prompt.
351
314
  - A repeat sync changes nothing.
352
315
  - After the merge, `ompRemovals.ts syncOmpRemovals, retired bash-rule
353
316
  inventory` removes the retired kit rules in `OMP_RETIRED_BASH_RULES` from
354
- the deployed `bash.patterns` on every sync. It removes a rule only when
355
- its `match` and `approval` equal a retired pair, so a different user rule
356
- stays.
317
+ the deployed `bash.patterns` on every sync. The inventory also holds the
318
+ 492 prompt rules that the kit retired in 0.22.8. It removes a rule only
319
+ when its `match` and `approval` equal a retired pair, so a different user
320
+ rule stays.
357
321
  - **Claude Code**: sync unions each permissions array with the deployed one,
358
322
  so user rules stay. `--reconcile` replaces the arrays with the SoT arrays.
359
323
  - **Codex**: sync writes `~/.codex/rules/docks.rules` whole. Keep your own
@@ -390,8 +354,5 @@ Each check below is safe, because the shell never reaches `rm`.
390
354
  `git status --porcelain` without `--ignored`).
391
355
  - Git hooks: https://git-scm.com/docs/githooks (`--no-verify`,
392
356
  `core.hooksPath`), https://git-scm.com/docs/git-commit and
393
- https://git-scm.com/docs/git-am (`-n`), https://git-scm.com/docs/git
394
- (`-c`, `--config-env`), and https://git-scm.com/docs/git-config (names
395
- without case, `GIT_CONFIG_COUNT`, `GIT_CONFIG_PARAMETERS`,
396
- `GIT_CONFIG_GLOBAL`).
357
+ https://git-scm.com/docs/git-am (`-n`).
397
358
  - macOS `trash`: https://keith.github.io/xcode-man-pages/trash.8.html
@@ -31,21 +31,20 @@ are versioned config snapshots without publishing the authoring `SoT/` tree.
31
31
  Kit-home resolution remains available for checkout/package update behavior and
32
32
  display paths, but sync reads do not depend on it.
33
33
 
34
- ### Bun 1.4.0 install output
34
+ ### Bun 1.4.4 install output
35
35
 
36
- A supported global install completes with no blocked postinstall: `bun pm -g
36
+ A supported global install completes with no blocked postinstall. The graph
37
+ holds nine packages, and no package in it has an install script. `bun pm -g
37
38
  untrusted` reports zero untrusted dependencies with scripts. Neither
38
- `@parcel/watcher` nor `esbuild` is in the consumer graph. The graph does carry
39
- one package with an `install` script, `msgpackr-extract` by way of
40
- `effect > msgpackr`, and Bun raises no trust prompt for it.
41
-
42
- The install prints no peer dependency warning. The root pins
43
- `@effect/platform-node-shared` at `4.0.0-rc.115`, the same release as the
44
- pinned `effect`, so a fresh registry resolution installs exactly one copy of
45
- each and the transitive peer range `effect@^4.0.0-rc.115` is satisfied. Without
46
- that root pin, `@effect/platform-bun` requests the shared package through a
47
- caret range over a prerelease and a fresh install can pair a newer shared
48
- package with the pinned `effect`.
39
+ `@parcel/watcher` nor `esbuild` is in the consumer graph.
40
+
41
+ The install prints no peer dependency warning. The root pins `effect`,
42
+ `@effect/platform-bun`, and `@effect/platform-node-shared` at exactly `4.1.2`.
43
+ `@effect/platform-bun@4.1.2` also pins `@effect/platform-node-shared` at
44
+ exactly `4.1.2`, and both packages accept `effect@^4.1.2` as a peer. So a
45
+ fresh registry resolution installs exactly one copy of each package. The root
46
+ pin of `@effect/platform-node-shared` lets the offline nested-copy guard catch
47
+ a copy that lags behind the pinned release.
49
48
 
50
49
  ## 3. curl installer (POSIX)
51
50
 
@@ -17,7 +17,7 @@ AI-assisted dev environment on every machine.
17
17
  | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
18
18
  | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
19
19
  | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain and the `docks-kit omp` session overlay |
20
- | `cli/` | This CLI (Effect 4 RC on Bun) plus bundled docs |
20
+ | `cli/` | This CLI (Effect 4 on Bun) plus bundled docs |
21
21
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: version-matching compiled binary → Bun-from-source, with Bun auto-install |
22
22
 
23
23
  ## Design rules
@@ -62,13 +62,13 @@ config.yml and models.yml are deep-merged (SoT keys win, mapping nodes merge,
62
62
  deployed-only keys survive; config.yml also drops stale slash-bearing
63
63
  `retry.fallbackChains` wildcards). A SoT list replaces the deployed list, except
64
64
  config.yml `bash.patterns`: the merge keeps user rules and groups all rules as
65
- kit deny, user deny, user prompt, kit allow exceptions (kit allows listed
66
- before the first kit prompt; the kit currently ships none), kit
67
- prompt, other user rules, and kit allow, so no allow loosens a deny or a prompt (see
65
+ kit deny, user deny, user prompt, kit prompt (the kit ships none since 0.22.8),
66
+ other user rules, and kit allow, so no allow loosens a deny or a prompt (see
68
67
  `docks-kit docs command-guards`). After each merge, every sync (no
69
68
  `--reconcile` needed) force-prunes the `ompRemovals.ts` retired-key inventory:
70
69
  the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
71
- `match` and `approval` pairs), config.yml keys whose deployed value still equals the value the kit used to
70
+ `match` and `approval` pairs, including the 492 former kit prompt rules
71
+ retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
72
72
  ship, `providers.webSearchOrder` at any value, and the retired
73
73
  `anthropic.modelOverrides.claude-opus-5-5` block in models.yml while it still
74
74
  matches the shipped block.
package/cli/src/argv.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { GlobalFlag } from "effect/unstable/cli";
1
+ import { GlobalFlag } from "effect/cli";
2
2
  import { docsCommand } from "./commands/docs";
3
3
  import { harnessesCommand } from "./commands/harnesses";
4
4
  import { modelCommand } from "./commands/model";