docks-kit 0.22.13 → 0.22.20
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 +94 -80
- package/README.md +7 -7
- package/cli/docs/command-guards.md +7 -3
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +14 -8
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +1 -1
- package/cli/docs/platforms.md +4 -2
- package/cli/docs/plugins.md +8 -5
- package/cli/docs/sync-layers.md +6 -4
- package/cli/docs/toolchain.md +24 -14
- package/cli/src/argv.ts +7 -4
- package/cli/src/argvValidate.ts +2 -16
- package/cli/src/commands/docs.ts +1 -1
- package/cli/src/commands/omp.ts +56 -15
- package/cli/src/commands/sync.ts +6 -6
- package/cli/src/commands/tidy.ts +83 -26
- package/cli/src/engine-native/DESIGN.md +93 -56
- package/cli/src/engine-native/atomicWrite.ts +168 -8
- package/cli/src/engine-native/codexConfig.ts +2 -6
- package/cli/src/engine-native/codexPlugins.ts +1 -1
- package/cli/src/engine-native/codexSync.ts +137 -26
- package/cli/src/engine-native/codexToml.ts +4 -86
- package/cli/src/engine-native/deps.ts +51 -51
- package/cli/src/engine-native/exec.ts +3 -0
- package/cli/src/engine-native/index.ts +1 -1
- package/cli/src/engine-native/kitLock.ts +121 -0
- package/cli/src/engine-native/modes.ts +49 -31
- package/cli/src/engine-native/ompChild.ts +26 -0
- package/cli/src/engine-native/ompFastMode.ts +14 -7
- package/cli/src/engine-native/ompFileDeploy.ts +12 -6
- package/cli/src/engine-native/ompMarketplace.ts +25 -18
- package/cli/src/engine-native/ompPlugins.ts +23 -14
- package/cli/src/engine-native/ompRemovals.ts +51 -23
- package/cli/src/engine-native/ompSync.ts +66 -32
- package/cli/src/engine-native/os/targets.ts +16 -4
- package/cli/src/engine-native/os/types.ts +1 -1
- package/cli/src/engine-native/parseArgs.ts +27 -17
- package/cli/src/engine-native/processes.ts +16 -0
- package/cli/src/engine-native/scratch.ts +18 -0
- package/cli/src/engine-native/skillsInstall.ts +27 -2
- package/cli/src/engine-native/skillsPrune.ts +51 -49
- package/cli/src/engine-native/skillsRecords.ts +138 -0
- package/cli/src/engine-native/skillsSync.ts +16 -13
- package/cli/src/engine-native/syncDispatch.ts +186 -4
- package/cli/src/engine-native/tidy.ts +102 -119
- package/cli/src/engine-native/tomlLines.ts +92 -0
- package/cli/src/generated/sotPayload.ts +4 -4
- package/cli/src/main.ts +5 -30
- package/cli/src/manifests.ts +24 -4
- package/package.json +2 -2
- package/cli/src/engine-native/tidyLock.ts +0 -163
package/AGENTS.md
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
Canonical instructions for coding agents working on this project. Compatible with OpenAI Codex, Claude Code (
|
|
3
|
+
Canonical instructions for coding agents working on this project. Compatible with OpenAI Codex, Claude Code (native AGENTS.md support, v2.1.277+), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
|
|
4
|
+
|
|
5
|
+
Pointers here name concepts, not coordinates — if a path or symbol moved,
|
|
6
|
+
trust the stated purpose and re-locate it (grep the symbol) before acting.
|
|
4
7
|
|
|
5
8
|
## Repository purpose
|
|
6
9
|
|
|
@@ -15,7 +18,7 @@ preserving rigorous output. When you add or edit anything, ask: *does this
|
|
|
15
18
|
change reduce tokens without weakening correctness?*
|
|
16
19
|
|
|
17
20
|
Tool-specific instructions live alongside this file:
|
|
18
|
-
-
|
|
21
|
+
- **`.claude/rules/claude-code.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns. Its `paths:` frontmatter scopes it: Claude Code loads it when it reads or edits a matching file, and any agent can open it by path.
|
|
19
22
|
- Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
|
|
20
23
|
- omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
|
|
21
24
|
|
|
@@ -24,61 +27,67 @@ docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
|
|
|
24
27
|
arm64, and Windows x64. Hosts outside this matrix fail before either
|
|
25
28
|
launcher can fall back to Bun source.
|
|
26
29
|
|
|
30
|
+
## Context tree
|
|
31
|
+
|
|
32
|
+
Per-folder conventions live in nested `AGENTS.md` nodes. Claude Code loads a
|
|
33
|
+
folder's AGENTS.md when it reads a file there; Codex loads only the nodes from
|
|
34
|
+
the root down to its working directory, so open the node for the folder you
|
|
35
|
+
edit from this table. Do not add CLAUDE.md files: a CLAUDE.md without an
|
|
36
|
+
`@AGENTS.md` import makes Claude read it instead of AGENTS.md. Edit the node,
|
|
37
|
+
not this list, when a folder's rules change. `context-tree audit` checks this
|
|
38
|
+
table against the AGENTS.md files on disk.
|
|
39
|
+
|
|
40
|
+
| Node | Governs |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `docs/AGENTS.md` | Plan-record routing to `docs/PLAN.md` |
|
|
43
|
+
| `cli/AGENTS.md` | Effect CLI, EngineNative sync engine, bundled docs topics, build scripts, unit and golden suites |
|
|
44
|
+
| `.agents/skills/AGENTS.md` | Project skills, the `.claude/skills/` symlinks, and the wrapper agents in `.claude/agents/` and `.codex/agents/`; Claude Code reads nothing under `.agents/`, so open this node from this table |
|
|
45
|
+
|
|
27
46
|
## Repository layout (cross-cutting)
|
|
28
47
|
|
|
29
48
|
| Path | Purpose |
|
|
30
49
|
|------|---------|
|
|
31
|
-
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json
|
|
32
|
-
| `cli/build-binaries.sh` | Compiles the four release binaries (`docks-kit-linux-x64`, `docks-kit-linux-arm64`, `docks-kit-darwin-arm64`, `docks-kit-windows-x64.exe`). It checksums the four known artifact names rather than globbing `docks-kit-*`, so a packed `docks-kit-<version>.tgz` is never attested as a release binary. It stamps `cli/dist/VERSION` only when the directory holds one version, and on the next build discards every artifact that stamp attributes to a different version, because a launcher refuses to run one and keeping it makes `SHA256SUMS` span two versions. An artifact with no stamp has unknown provenance and may be a hand-built or downloaded recovery binary, so the script keeps it and warns; `--prune` discards those too. Nothing here removes an artifact the stamp vouches for. |
|
|
33
|
-
| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
|
|
34
|
-
| `cli/src/engine-native/ompSync.ts` | omp sync orchestration and summary |
|
|
35
|
-
| `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: rejects model-selecting forwarded flags, checks the free catalog of each candidate profile, renders the free-model run overlay, and starts `omp launch` |
|
|
36
|
-
| `cli/src/checklistPrompt.ts` / `cli/src/terminalCells.ts` | Shared terminal checklist prompt on Effect's `Prompt.Custom`: items, a Save row, key hints, an ASCII fallback, and NO_COLOR; `docks-kit harnesses` uses it. `terminalCells.ts` measures text in terminal cells and rows from the pinned Unicode 18.0.0 East Asian Width table; derive the table again from a newer `EastAsianWidth.txt` the same way its header says |
|
|
37
|
-
| `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render, omp argv and child environment, plus catalog parse and thinking-ceiling helpers |
|
|
38
|
-
| `cli/src/engine-native/scratch.ts` / `cli/src/commands/scratch.ts` | `docks-kit scratch new\|remove`: private agent temporary directories under `~/.cache/docks-kit/scratch/`; removal accepts only a real path strictly inside the scratch root, the system temporary directory, or `/var/tmp` |
|
|
39
|
-
| `cli/src/engine-native/tidy.ts` / `tidyReport.ts` / `cli/src/commands/tidy.ts` | `docks-kit tidy [--apply] [--repo <path>] [--report]`: plan and apply the safe leftover sweep (merged idle worktrees and their containers, orphaned processes in agent directories, idle scratch); Docker calls run only against a verified local endpoint (`unix:///…` or `npipe:////./pipe/…`); the report is read-only |
|
|
40
|
-
| `cli/src/engine-native/ompKitPlugin.ts` | Materializes the `SoT/.omp/plugin/` payload to `~/.docks-kit/omp-plugin` with the kit version; `ompPlugins.ts syncPlugins` links it |
|
|
41
|
-
| `cli/src/engine-native/<axis>.ts` | One change axis per file: `codexConfig`/`codexHooks`/`codexPlugins`/`codexStatus`, `claudeSettings`/`claudeRemovals`/`claudePluginPasses`/`claudeOptionalPlugins`/`claudeLsp`, `parseModifiers`/`parseHelp`, `ompFileDeploy`/`ompMarketplace`/`ompPlugins`, `skillsManifest`/`skillsLinks`/`skillsInstall`/`skillsPrune`, `engineCtx`/`syncConcurrency`/`syncDispatch`; orchestrators keep prior exports |
|
|
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
|
-
| `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
|
-
| `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` |
|
|
50
|
+
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json` and no file under `cli/src/` or `cli/docs/` is newer than the binary. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`, and the mismatch or newer-source warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
|
|
45
51
|
| `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
|
|
46
|
-
| `cli/test/fixtures/` | Golden fixtures: `home-fresh`, `home-drift`, `home-invalid-json`, `codex-toml`, `statusline` |
|
|
47
52
|
| `cli/` | Effect 4 CLI + bundled docs topics |
|
|
48
53
|
| `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
54
|
| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
|
|
50
55
|
| `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
|
|
51
|
-
| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`,
|
|
56
|
+
| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
|
|
52
57
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
|
|
53
58
|
| `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
|
|
54
59
|
| `README.md` | Front door |
|
|
55
60
|
| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
|
|
56
61
|
| `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap and Claude symlink. |
|
|
57
62
|
| `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
|
|
58
|
-
| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it
|
|
59
|
-
|
|
|
63
|
+
| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
|
|
64
|
+
| `.claude/rules/claude-code.md` | Claude Code-only instructions; path-scoped by its `paths:` frontmatter |
|
|
65
|
+
| `.claude/settings.json` | Project Claude Code settings. It holds only `claudeMdExcludes`, so Claude Code does not load the SoT prompt payloads or the test fixtures as project instructions; sync never reads or writes it |
|
|
60
66
|
| `AGENTS.md` | This file — tool-agnostic instructions |
|
|
61
67
|
|
|
68
|
+
Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
|
|
69
|
+
|
|
62
70
|
Codex SoT notes:
|
|
63
71
|
- `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
|
|
64
72
|
- `SoT/.codex/config.toml` pins Codex to `model = "gpt-6.1-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the two Docks plugins `docks@docks` and `plan-lifecycle@docks` (the shared plan lifecycle).
|
|
65
73
|
- `SoT/.codex/config.toml` does not set `personality`. Codex 0.159.0 deprecated the key, and `friendly` and `pragmatic` no longer select a style. `codexConfig.ts removeRetiredTopLevelSettings, retired top-level key prune` removes the retired `personality = "pragmatic"` line from a deployed `config.toml` on every sync. A different user-set value survives.
|
|
66
74
|
- `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved. Codex applies the strictest matching rule across all files, so a user allow rule cannot loosen a kit `forbidden` or `prompt` rule. Because the strictest rule wins, a narrow allow cannot carve an exception out of a broader prompt prefix, and a prefix rule cannot see an option after an operand. The guards therefore fail closed: every `rm`, `git rm`, `git worktree remove`, and `gio trash` prompts, and only macOS `trash` is allowed (owner decision). A `prompt` goes to `approvals_reviewer = "auto_review"`, a reviewer subagent, not always to a person. `docks.rules` carries the destructive-command guards (`docks-kit docs command-guards`); `cli/test/unit/codexSyncRules.test.ts` parses every one-line `prefix_rule`, alternatives lists and `justification` included, and asserts each guard's decision. Keep each rule on one line so that parser sees it.
|
|
75
|
+
- `codexSync.ts syncRules, kit rules manifest` records the sha256 of the kit bytes of each rules file that the kit deploys in `~/.codex/.kit-managed-rules`, in `<sha256> <file name>` lines. The manifest sits outside `rules/`, so Codex never reads it as a rule file. Sync writes each rules file through `atomicWrite.ts replaceFile`, so an interrupted write keeps the previous file. Codex loads only `*.rules` files, so it never loads the `*.tmp` sibling. Before the deploy, sync writes the manifest ahead. It keeps the recorded set of hashes of each name and adds the new kit hash of each shipped name. So a name whose kit bytes change has two lines. A sync that stops after a deploy thus leaves a record of the bytes that it wrote. A stale kit rules file keeps its old rules active. When the SoT drops a rules file, every sync therefore removes the deployed copy while its hash is in the recorded set of its name. A dropped file that the user edited stays, keeps its set, and gets a warning on each sync. Every recorded hash is a hash of kit bytes, so no record lets cleanup remove bytes that the user wrote. Cleanup reads and removes only recorded names that the SoT no longer ships. It never reads or removes a file that the SoT does not ship and no sync recorded, such as `default.rules`. Sync still deploys each name that the SoT ships over an existing file, recorded or not. It backs up a file that differs to `<name>.bak` and replaces it. After the deploy and the cleanup, the final manifest holds one line per shipped name, plus the set of each kept dropped name. Sync replaces the manifest through a temporary file and a rename, so an interrupted sync keeps the previous complete manifest. `--dry-run` prints `[dry-run] remove <file>` and writes nothing.
|
|
67
76
|
- `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
|
|
68
|
-
- Codex `/import`
|
|
77
|
+
- Codex `/import` hook cleanup (`codexHooks.ts`): `cli/AGENTS.md`.
|
|
69
78
|
- Codex limits the initial skill list to 2% of the model context and shortens descriptions first; it still reads a selected skill's full `SKILL.md`. Additive sync preserves user-added plugins, so their skill count and malformed cached `SKILL.md` files remain plugin-owned. Sync never patches a plugin cache in place.
|
|
70
79
|
- The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
|
|
71
80
|
- The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
|
|
72
81
|
|
|
73
82
|
- Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
|
|
74
83
|
- Claude's deployed SoT defaults are `model: opus` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: opus` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.280 makes Claude Code resolve it to Opus 5.5, the default Opus from that release, instead of capping at Opus 5 under the former 2.1.219 floor. Keeping the alias tracks the next Opus release without a kit change and stays portable across providers. The floor also subsumes Fable 5.1's 2.1.257 requirement.
|
|
75
|
-
- Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeRemovals.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries
|
|
84
|
+
- Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeRemovals.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries, `Read`, `Glob`, `Grep`, and `WebSearch`, the working-directory edit rule `Edit(./)`, and two narrow trash allows, `Bash(gio trash -- *)` and `Bash(trash *)`. Broad shell allow rules are not restored, because an allow rule resolves before Claude Code's read-only command analyzer and the auto-mode classifier. `autoMemoryEnabled` and `autoDreamEnabled` are both `false`.
|
|
76
85
|
|
|
77
86
|
omp SoT notes:
|
|
78
87
|
- `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
|
|
79
88
|
- `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
89
|
- `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. 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
|
|
90
|
+
- `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`, and `gio trash`. Since 0.21.0 it also covers `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.17.0'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
91
|
- `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
92
|
- `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
93
|
- `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.1-sol:high`. `task.enableEffort` is `false`: a caller `effort` outranks the role's level suffix, and `hi` maps to the top of the model ladder, so with the field on, `hi` spawns ran at `task.maxEffort` (`xhigh`) instead of the role level. With the field off, every spawn runs its role level, and `task.maxEffort` bounds only a per-call `model` with a `:level` suffix. `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-terra:high`. Its retry fallback is `anthropic/claude-opus-5-5:high`. All four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `task.agentServiceTierOverrides` sets the same four agents to `inherit`, so they take the live tier of the main session for each provider. The user set the effort `high` and chose to follow the fast toggle (#134); the review benchmark of #130 chose the model. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. omp bundles the `reviewer` and `security-reviewer` agents, and the `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`. 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.
|
|
@@ -87,37 +96,26 @@ omp SoT notes:
|
|
|
87
96
|
- `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. The temporary `anthropic.modelOverrides.claude-opus-5-5` block is gone, because the shared catalog now publishes the same limits, ladder, and prices. The removal switches omp from the block's `thinking.mode: effort` (a `budget_tokens` value per level from `ANTHROPIC_THINKING`, no effort value) to the catalog's `anthropic-adaptive` (adaptive thinking with the role's effort level); every kit Opus selector names its level, so the block's bare-selector `defaultLevel: high` is not needed. `ompRemovals.ts syncOmpModelRemovals, retired-block inventory` prunes it from `~/.omp/agent/models.yml` after the models merge, but only while the deployed block still equals the shipped one. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
|
|
88
97
|
- `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
|
|
89
98
|
- `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change.
|
|
90
|
-
- `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)
|
|
91
|
-
- Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope. omp deletes the previous plugin folder on upgrade, so running omp sessions lose that plugin's agents. A test on omp 18.16.0 showed that `/reload-plugins` brings the agents back, and that `skill://` resolves to the new folder (#139). When an upgrade changes a version, `ompPlugins.ts syncPlugins, upgrade log` warns, sets the `ompPluginUpgraded` next-step trigger, and writes one event file into `~/.cache/docks-kit/omp-plugin-upgrades/`. The warning and the next step give one rule: run `/reload-plugins` in each running session, then read each plugin skill again through `skill://`. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools, as the omp marketplace docs say. A version-changing upgrade does not set `ompRestart`. Each other plugin operation sets it: an install, a reinstall at the same version, an npm install, or a link. A changed kit plugin or config file also sets it. The restart next step then prints next to the upgrade rule. If the versions cannot be read after the upgrade, it warns once more, and each upgrade counts as a change to the version `unknown`. A failed write of the log only warns; it does not fail the sync. The log keeps the newest 100 event files; `cli/docs/sync-layers.md` gives the file format and the limits.
|
|
92
|
-
- Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
|
|
99
|
+
- `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)`. The trigger is 425,000 on the 500,000-token windows of GPT-6.1 Sol and Terra, 231,200 on the 272,000-token windows of GPT-6 Luna and Astra, and 850,000 on the 1,000,000-token Anthropic window. The key ships as `-1` rather than being deleted because `ompYaml.ts mergeOmpConfig` is additive, so removing a key from SoT never removes it from a deployed file. `cli/docs/omp-context.md` (topic `omp-context`) carries the derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
|
|
93
100
|
- Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`). It sets directories to 0700, files to 0600, and the `package.json` `version` to the kit version, and it removes stale files. It keeps no backups, because the directory is kit-owned. `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>`. It skips the link when 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 `hygiene.ts` extension registers `scratch_new`, `scratch_remove`, and `tidy_report`. It adds a reminder after each bash command that created a resource, and it checks at session stop that those resources are gone. At a main-session start, it 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 `pluginUpgrades.ts` extension reads the omp plugin upgrade log. In a tool result of each main session, it adds one reminder for the logged upgrades that the session did not get before. It names only the upgrades that finished after its omp process started. The reminder tells the agent to ask the user to run `/reload-plugins`. It then tells the agent to read each plugin skill again through `skill://` before it runs a skill script. It asks for a restart instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools. omp imports extensions only at startup. An omp process that started before a sync deployed `pluginUpgrades.ts` did not load it, so its sessions get no reminder. 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
101
|
- `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
|
|
95
102
|
- 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
103
|
- 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
|
-
-
|
|
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.
|
|
99
|
-
- The session model persists per machine in `~/.docks-kit/kit.db` (table `omp_session`), next to the harness selection. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. Every launch, a plain launch included, runs `omp models --json` for the profile of the environment and `omp --profile <name> models --json` for each forwarded `--profile` value, and checks the remembered or default model against each live free catalog. When that model is not free in every one of these catalogs, the launcher stops with an error and does not start omp. `--model` and `--pick` resolve against the catalog of the last forwarded profile. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only catalog models at zero input and output cost with `pricingStatus` free or unknown.
|
|
100
|
-
- `docks-kit omp --fast` toggles `tier.openai` in the deployed `~/.omp/agent/config.yml` between `priority` (omp's `/fast on` tier for OpenAI and OpenAI-Codex models) and `none`, prints the change, and exits. `ompFastMode.ts toggleOpenAiFast` edits only that key. `SoT/.omp/config.yml` does not declare `tier.openai`, so the additive merge keeps the toggled value across sync. The four review agents inherit the live tier of the main session, so they follow the toggle in a new session; a running session keeps its tier. `--fast` never changes the Anthropic tier, and sync sets the deployed `tier.anthropic` to the SoT value `none`, so each session starts with it. `/fast on` in an Opus session sets `anthropic: priority` for that session, and the reviewers and their Opus fallback inherit it; omp has no override that inherits only the OpenAI tier. There is no Ultrafast flag: omp ignores `ultrafast` for a Codex model whose catalog `serviceTiers` omits it, and the current GPT models omit it.
|
|
104
|
+
- omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
|
|
101
105
|
|
|
102
106
|
For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
|
|
103
107
|
|
|
104
108
|
## Engineering rules
|
|
105
109
|
|
|
106
|
-
- **
|
|
107
|
-
- **
|
|
108
|
-
- **
|
|
109
|
-
-
|
|
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
|
-
- **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
|
-
- **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
|
-
- **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.
|
|
114
|
-
- **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` removes what SoT does not declare: every user-scope Claude plugin whose id is absent from SoT `enabledPlugins` (third-party and previously opted-in plugins included, unless this run passes their `--claude-plugin` flag), every Claude marketplace except `claude-plugins-official`, SoT/opt-in plugin marketplaces, and marketplaces referenced by project/local installs, and the `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills` that SoT no longer lists. Combine with `--reconcile` for a full reset to SoT. Always preserved: user-only settings keys (custom env vars, mcpServers), manually-installed skills, and project/local-scope plugin installs. Each tool's per-tool file documents the specific paths and diff recipes.
|
|
115
|
-
- **SOLID-aligned modules.** Axis modules own one concern each (see layout); orchestrators (`claudeSync.ts`, `codexSync.ts`, `skillsSync.ts`, `ompSync.ts`, `index.ts`, `argv.ts`, `parseArgs.ts`) keep prior exports. New shared shapes go in `sharedTypes.d.ts`, never a second local copy. The public CLI seam is `cli/src/engine.ts`.
|
|
110
|
+
- **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing, harness-selection store, module boundaries): `cli/AGENTS.md`.
|
|
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 § Deploy-time modifiers under `## Setup` in this file, and the Claude table in `.claude/rules/claude-code.md` § Deploy-time modifiers).
|
|
112
|
+
- **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/rules/claude-code.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.
|
|
113
|
+
- **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` removes what SoT does not declare: every user-scope Claude plugin whose id is absent from SoT `enabledPlugins` (third-party and previously opted-in plugins included, unless this run passes their `--claude-plugin` flag), every Claude marketplace except `claude-plugins-official`, SoT/opt-in plugin marketplaces, and marketplaces referenced by project/local installs, and the `~/.agents/skills/*` entries named in `~/.agents/.kit-owned-skills` that SoT no longer lists. A slug enters that record only when an install of the kit created its directory, so a directory that existed before is never recorded. `--prune` removes it only while the directory keeps the `<dev>:<ino>` that the record names; else it prints `keep <slug>: the directory is not the one that the kit installed`. The legacy `~/.agents/.kit-managed-skills` of an older kit is read only and never authorizes a removal. `--prune` prints a `keep <slug>` line for each of its dropped slugs whose directory exists. Combine with `--reconcile` for a full reset to SoT. Always preserved: user-only settings keys (custom env vars, mcpServers), manually-installed skills, and project/local-scope plugin installs. `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune` documents the Claude paths and diff recipes.
|
|
116
114
|
- **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
|
|
117
115
|
- **Version bumps.** Bump `package.json` on user-visible behavior change; bump a `SoT/toolchain.json` `verified` pin only after testing that release. Refactors, splits, and doc edits bump nothing.
|
|
118
|
-
- **Regenerate the payload.** After `SoT/`, `notification.mp3`,
|
|
119
|
-
- **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in
|
|
120
|
-
- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md`, `SoT/.codex/AGENTS.md`, and `SoT/.omp/AGENTS.md` are loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `
|
|
116
|
+
- **Regenerate the payload.** After `SoT/`, `notification.mp3`, or `package.json` changes, run `bun cli/scripts/generate-sot-payload.ts`; `bun run check:generated` verifies it. After file moves, clamp cited `metadata.source_files[].lines` ranges so `skillMetadata.test.ts` passes.
|
|
117
|
+
- **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune`) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
|
|
118
|
+
- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md`, `SoT/.codex/AGENTS.md`, and `SoT/.omp/AGENTS.md` are loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `AGENTS.md` or `.claude/rules/claude-code.md` (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
|
|
121
119
|
- **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, hook outputs that land in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages (e.g. SessionStart hook output), which is exactly how the kit's date/config injection works.
|
|
122
120
|
|
|
123
121
|
## Code style
|
|
@@ -129,47 +127,27 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
|
|
|
129
127
|
|
|
130
128
|
- No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
|
|
131
129
|
- 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`, 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
|
-
- **
|
|
130
|
+
- **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version, except the exemptions in the next item — 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`.
|
|
131
|
+
- **Exemptions: the kit's own package, two host-toolchain installs, and the existing marketplace plugins.** `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 `@latest` 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. Two host-toolchain installs have no pin, because the host toolchain controls their version and the kit does not: `claudeLsp.ts installRustAnalyzer` adds `rust-analyzer` through `rustup component add rust-analyzer`, and `codexSync.ts ensureBubblewrap` installs `bubblewrap` through the distro package manager. Their `SoT/toolchain.json` rows (`rust-analyzer`, and `bwrap` with a floor only) and `cli/docs/toolchain.md` record this. The existing Claude Code, Codex, and omp marketplace plugin installs have no manifest pin either: sync installs and refreshes those plugins at the version that their marketplace publishes. Any new install surface, a new marketplace or plugin source included, still needs a manifest pin first.
|
|
134
132
|
## Testing
|
|
135
133
|
|
|
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
|
|
134
|
+
Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests 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 `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune`.
|
|
137
135
|
|
|
138
136
|
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
137
|
|
|
140
|
-
|
|
138
|
+
Spawning-suite bundle and `DOCKS_KIT_TEST_CLI_ENTRY`: `cli/AGENTS.md`.
|
|
141
139
|
|
|
142
140
|
## Landing changes
|
|
143
141
|
|
|
144
|
-
Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every
|
|
142
|
+
Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every reported check to finish, then ask before merge. A failed or cancelled check blocks the merge. Push direct to `main` only for prose: root Markdown and code comments.
|
|
145
143
|
|
|
146
144
|
Never rewrite published `main` history to correct a routing mistake. Use a follow-up commit and say what happened.
|
|
147
145
|
|
|
148
146
|
## Skills
|
|
149
147
|
|
|
150
|
-
|
|
151
|
-
Canonical project skills live in `.agents/skills/<name>/SKILL.md`.
|
|
152
|
-
Each `.claude/skills/<name>` entry is a relative symlink to its canonical directory.
|
|
153
|
-
Codex reads `.agents/skills/` natively, so one copy serves both tools.
|
|
154
|
-
Kit-mechanic skills document regression-prone TypeScript sync logic in `cli/src/engine-native/`.
|
|
155
|
-
Kit-mechanic skills: `codex-config-merge-context`, `engine-native-context`, `plugin-bootstrap-context`, `settings-merge-context`, `sync-orchestration-context`, `toolchain-context`, `universal-skills-context`, and `omp-sync-context`.
|
|
156
|
-
**Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
|
|
157
|
-
|
|
158
|
-
**Windows checkouts.** These nine entries are the only symlinks this repository tracks. Git for Windows defaults to `core.symlinks=false`, which checks a symlink out as a plain file holding the target path, so Claude Code finds no `SKILL.md` and silently loads no project skill. Codex is unaffected, because it reads the real directories under `.agents/skills/`. To restore Claude Code on Windows, enable Developer Mode or run as administrator, then `git config core.symlinks true` and re-checkout the paths: `git checkout -- .claude/skills`. Never repair this by replacing an entry with a copy; two copies drift, which is the failure the canonical layout removes. This limitation is confined to project skills in this checkout. It does not affect the deployed user-level skills, where `skillsSync.ts linkOrCopyWithWarnings` already falls back from symlink to junction to marked copy.
|
|
148
|
+
Project-skill and wrapper-agent authoring rules (scope, canonical layout, Windows symlinks, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
|
|
159
149
|
|
|
160
|
-
`npx skills add
|
|
161
|
-
The repository vendors upstream `unslop` text and pins it by the lockfile hash, so never edit it locally.
|
|
162
|
-
Upstream licenses `pstack/` under MIT (Copyright (c) 2026 Lauren Tan), so redistribution is permitted.
|
|
163
|
-
MIT requires the notice to travel with the copy, so `.agents/skills/unslop/LICENSE` vendors it verbatim and must stay beside `SKILL.md`.
|
|
164
|
-
The `unslop` "adding soul" guidance conflicts with the global Simplified Technical English Output Standard.
|
|
165
|
-
The Output Standard wins.
|
|
166
|
-
Use `unslop` only for its pattern-detection lists.
|
|
167
|
-
|
|
168
|
-
<constraint>
|
|
169
|
-
When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudePluginPasses.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
|
|
170
|
-
</constraint>
|
|
171
|
-
|
|
172
|
-
**Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsInstall.ts syncUniversal` with `npx --yes skills@<verified> add <slug> -g -y -a claude-code codex`, where `<verified>` is the `skills-cli` pin in `SoT/toolchain.json`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently, `--prune` removes only entries tracked in `~/.agents/.kit-managed-skills`, and skills requiring a separate CLI retain explicit helpers in `skillsSync.ts`.
|
|
150
|
+
**Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsInstall.ts syncUniversal` with `npx --yes skills@<verified> add <slug> -g -y -a claude-code codex`, where `<verified>` is the `skills-cli` pin in `SoT/toolchain.json`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently and are never recorded as kit-owned. When no record names a reused directory, sync warns that `--prune` keeps it. Before an install, sync records the slug in `~/.agents/.kit-pending-skills`, and only when the canonical directory does not exist. After the install, the slug moves to `~/.agents/.kit-owned-skills` when its directory exists. `--prune` removes only entries in `~/.agents/.kit-owned-skills`; the legacy `~/.agents/.kit-managed-skills` is read only and never authorizes a removal (`skillsRecords.ts`).
|
|
173
151
|
|
|
174
152
|
## Plans
|
|
175
153
|
|
|
@@ -191,7 +169,7 @@ review, implement, and code review. It uses bounded repair and fresh re-review
|
|
|
191
169
|
in both review phases, then archives. Internal `plan-reviewer` returns one
|
|
192
170
|
readable pre-implementation verdict block per round. Two read-only reviewer
|
|
193
171
|
wrappers ship: `plan-reviewer` and `code-reviewer`.
|
|
194
|
-
The explicit-only `yolo` skill runs the same workflow
|
|
172
|
+
The explicit-only `yolo` skill runs the same workflow. It still asks before merge, on a review stall, before a production cleanup, and before a step after the landing merge, as the contract's Yolo runs section says.
|
|
195
173
|
</constraint>
|
|
196
174
|
|
|
197
175
|
After the marker and blank line, the record carries exactly seven sections.
|
|
@@ -205,8 +183,12 @@ GitHub `state` and `stateReason` determine closed status. Review records live
|
|
|
205
183
|
only in issue comments. Each reviewer returns one markdown block.
|
|
206
184
|
The manager posts that block as one issue comment. The latest trusted eligible
|
|
207
185
|
comment per review kind wins. Its author must equal the plan's sole assignee.
|
|
208
|
-
Both review phases use fresh inputs
|
|
209
|
-
pass
|
|
186
|
+
Both review phases use fresh inputs for each round. They stop on
|
|
187
|
+
pass. Ask the user to continue or block when a round makes no progress, the
|
|
188
|
+
same finding returns after a repair, round 5 does not pass, or dispatch fails
|
|
189
|
+
again without a relevant change. If no answer is available, record the reason
|
|
190
|
+
and block. A yolo run uses the round ceiling of the contract's Yolo runs
|
|
191
|
+
section instead.
|
|
210
192
|
A plan-review `blocked` verdict routes its user-only decision through
|
|
211
193
|
`## Open questions` and `ask`.
|
|
212
194
|
|
|
@@ -237,20 +219,18 @@ before it runs; when `ask` is unavailable the step is set `blocked` and the plan
|
|
|
237
219
|
reason becomes the first `## Open questions` line, `Blocked: <reason>`.
|
|
238
220
|
Persisted effects record intent only. Routine issue publication and landing
|
|
239
221
|
actions are outside the Steps table.
|
|
240
|
-
A user-invoked `yolo` run replaces these asks, the
|
|
222
|
+
A user-invoked `yolo` run replaces these asks, the continue-or-block question of the review loop, and the `blocked`-verdict question with the Yolo runs section of the installed `plan-lifecycle` contract.
|
|
241
223
|
|
|
242
224
|
Render a plan body verbatim only when the user names that plan and asks to see it. After a write, report the one-line header strip and the changed lines only; a write never re-renders the body.
|
|
243
225
|
|
|
244
226
|
No plan markdown is tracked. The pre-GitHub records under
|
|
245
227
|
`docs/plans/finished/` were deleted; `git log -- docs/plans/finished/` recovers
|
|
246
228
|
them as history, and no lifecycle command restores them. The complete contract
|
|
247
|
-
lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it
|
|
248
|
-
contains only `@AGENTS.md`.
|
|
229
|
+
lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it.
|
|
249
230
|
|
|
250
|
-
Distinct from
|
|
251
|
-
blockers tied to a vendor shipping a fix
|
|
252
|
-
|
|
253
|
-
conditions-for-resolution.
|
|
231
|
+
Distinct from the **Open Concerns** section of `.claude/rules/claude-code.md`
|
|
232
|
+
(wait-on-upstream blockers tied to a vendor shipping a fix): plans are
|
|
233
|
+
kit-internal work we control; Open Concerns is conditions-for-resolution.
|
|
254
234
|
|
|
255
235
|
Plugin-internal work (skills, commands, agents) belongs in each plugin's
|
|
256
236
|
own repo, not here.
|
|
@@ -258,3 +238,37 @@ own repo, not here.
|
|
|
258
238
|
## Notes for nested overrides
|
|
259
239
|
|
|
260
240
|
Per the agents.md open standard, place an `AGENTS.md` inside any subdirectory that needs different rules. The closest `AGENTS.md` to the file being edited wins; explicit user prompts override everything.
|
|
241
|
+
|
|
242
|
+
## Setup
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
# Clone and sync the kit
|
|
246
|
+
git clone <this-repo> ~/projects/public
|
|
247
|
+
cd ~/projects/public
|
|
248
|
+
./docks-kit harnesses # view or change this machine's flag-less sync selection
|
|
249
|
+
./docks-kit sync # sync this machine's harness selection (additive)
|
|
250
|
+
./docks-kit sync --dry-run # preview before applying
|
|
251
|
+
./docks-kit sync --skip-bubblewrap # skip optional bubblewrap bootstrap (Codex Linux sandbox)
|
|
252
|
+
./docks-kit sync --reconcile # reconcile settings toward SoT: SoT keys and arrays win, user-only keys kept (settings layer only)
|
|
253
|
+
./docks-kit sync --prune # uninstall plugins/marketplaces not in SoT (plugin layer only)
|
|
254
|
+
./docks-kit sync --reconcile --prune # full reset to SoT (both layers)
|
|
255
|
+
./docks-kit sync claude --claude-compact-window=680k # deploy-time: raise autocompact window (any token count: 680k or 680000) for disposable sessions (model unchanged)
|
|
256
|
+
./docks-kit sync claude --claude-permissive # deploy-time: empty permissions.ask/deny — unattended commits/pushes in sandboxes
|
|
257
|
+
./docks-kit sync --claude-plugin=supabase # opt in the supabase plugin (install + enable in deployed settings)
|
|
258
|
+
./docks-kit sync --claude-plugin=n8n # opt in the n8n-mcp-skills plugin (add marketplace + install + enable); repeatable/comma-separated
|
|
259
|
+
./docks-kit model claude opus # deploy-time: set Opus explicitly (matches the SoT; standalone form of --claude-model=)
|
|
260
|
+
./docks-kit status # show deployed vs SoT state
|
|
261
|
+
./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout
|
|
265
|
+
commands.
|
|
266
|
+
|
|
267
|
+
For Codex plugins, after deploying `SoT/.codex/config.toml` and the personal marketplace file, sync runs `codex plugin add <plugin@marketplace>` for each enabled SoT plugin. Re-running sync therefore refreshes stale Codex plugin caches instead of only updating marketplace metadata. Sync also removes the older kit-created configured Docks marketplace source so Codex uses the personal marketplace file as the single source.
|
|
268
|
+
|
|
269
|
+
### Deploy-time modifiers
|
|
270
|
+
|
|
271
|
+
Unlike `--reconcile`/`--prune` (which reconcile toward SoT), modifiers change the **deployed** config for a specific machine profile. The SoT is never touched, and a later flag-less sync reasserts it: Claude returns to Opus/high/advisor-off and Codex returns to its model/high effort. Modifiers run after the base merge/removal passes, are idempotent, honor `--dry-run`, and warn when their tool target is not selected. `docks-kit model <tool> <value>` is the standalone form of the model modifiers.
|
|
272
|
+
|
|
273
|
+
Codex mirrors the model/effort contract with `--codex-model=<m>` and
|
|
274
|
+
`--codex-effort=<level>`; Codex `default` effort restores `high`.
|
package/README.md
CHANGED
|
@@ -127,11 +127,11 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
|
127
127
|
`docks-kit docs command-guards`.
|
|
128
128
|
- **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
|
|
129
129
|
directories and removes agent temporary files and directories with checked
|
|
130
|
-
paths
|
|
131
|
-
orphaned processes, and idle scratch directories
|
|
132
|
-
disk and memory use. The kit
|
|
133
|
-
|
|
134
|
-
once per 12 hours.
|
|
130
|
+
paths. `docks-kit tidy` lists merged idle worktrees, their containers,
|
|
131
|
+
orphaned processes, and idle scratch directories, and `docks-kit tidy
|
|
132
|
+
--apply` removes them; `--report` lists other disk and memory use. The kit
|
|
133
|
+
omp plugin `docks-kit-omp` exposes these as tools, reminds the agent of
|
|
134
|
+
what it created, and runs the sweep at most once per 12 hours.
|
|
135
135
|
|
|
136
136
|
## Repository map
|
|
137
137
|
|
|
@@ -149,7 +149,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
|
|
|
149
149
|
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
|
|
150
150
|
| `install.sh` / `install.ps1` | POSIX and Windows global installers |
|
|
151
151
|
| `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
|
|
152
|
-
| `AGENTS.md` /
|
|
152
|
+
| `AGENTS.md` / `.claude/rules/claude-code.md` | Agent-facing engineering rules / Claude Code specifics (path-scoped rule) |
|
|
153
153
|
|
|
154
154
|
## Platform support
|
|
155
155
|
|
|
@@ -180,5 +180,5 @@ are versioned config snapshots without shipping the authoring `SoT/` tree.
|
|
|
180
180
|
omp-models, omp-context, command-guards, toolchain, plugins, install,
|
|
181
181
|
platforms (works offline, bundled with the CLI)
|
|
182
182
|
- [`AGENTS.md`](AGENTS.md) — engineering rules for agents working on the kit
|
|
183
|
-
- [
|
|
183
|
+
- [`.claude/rules/claude-code.md`](.claude/rules/claude-code.md) — Claude Code specifics: env vars, session
|
|
184
184
|
management, permission mode, open concerns
|
|
@@ -55,7 +55,7 @@ that `eval` starts.
|
|
|
55
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) |
|
|
56
56
|
| `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny | ask if recursive, else classifier | ask |
|
|
57
57
|
| Any other `rm`: one file, several files, a glob, `-f` | run | glob asks; the rest goes to the classifier | ask |
|
|
58
|
-
| `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask | ask (every `find` asks) |
|
|
58
|
+
| `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask for `-delete`, `-exec rm` and `-execdir rm`; `-ok`/`-okdir rm` and a non-recursive `xargs rm` go to the classifier | ask (every `find` asks) |
|
|
59
59
|
| `git clean`, `git reset --hard` | run | ask | ask |
|
|
60
60
|
| `git push` that could force: see below | run, unless a deny above matches | ask | ask (every `git push` asks) |
|
|
61
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) |
|
|
@@ -322,7 +322,11 @@ prompt. In Claude Code, any form with `--empty` or `--restore` asks.
|
|
|
322
322
|
so user rules stay. `--reconcile` replaces the arrays with the SoT arrays.
|
|
323
323
|
- **Codex**: sync writes `~/.codex/rules/docks.rules` whole. Keep your own
|
|
324
324
|
rules in another `.rules` file, such as `default.rules`. Codex applies the
|
|
325
|
-
strictest rule across all files.
|
|
325
|
+
strictest rule across all files. Sync records each kit rules file in
|
|
326
|
+
`~/.codex/.kit-managed-rules`. When the SoT drops a kit rules file, sync
|
|
327
|
+
removes the deployed copy while it holds the kit bytes. A dropped file that
|
|
328
|
+
you edited stays, and each sync warns about it. Sync never removes a file
|
|
329
|
+
that it did not write, such as `default.rules`.
|
|
326
330
|
|
|
327
331
|
## Check the deployed rules
|
|
328
332
|
|
|
@@ -338,7 +342,7 @@ Each check below is safe, because the shell never reaches `rm`.
|
|
|
338
342
|
## Sources
|
|
339
343
|
|
|
340
344
|
- omp: `omp://tools/bash.md`, `omp://approval-mode.md`, and the
|
|
341
|
-
`@oh-my-pi/pi-coding-agent` 18.
|
|
345
|
+
`@oh-my-pi/pi-coding-agent` 18.17.0 source `src/tools/bash.ts`
|
|
342
346
|
(`CRITICAL_BASH_PATTERNS`, `BashTool.approval`).
|
|
343
347
|
- Claude Code: https://code.claude.com/docs/en/permissions and
|
|
344
348
|
https://code.claude.com/docs/en/permission-modes
|