docks-kit 0.24.0 → 0.25.0

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
@@ -2,42 +2,24 @@
2
2
 
3
3
  Canonical instructions for coding agents working on this project. Compatible with Oh My Pi (`omp`), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
4
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.
5
+ Pointers here name concepts, not coordinates — if a path or symbol moved, trust the stated purpose and re-locate it (grep the symbol) before acting.
7
6
 
8
7
  ## Repository purpose
9
8
 
10
- Portable configuration kit for AI coding agents. The kit manages one coding
11
- harness, Oh My Pi (`omp`). Its Single Source of Truth (SoT) directory deploys
12
- to omp's user-config location through `./docks-kit sync`. Sync writes no
13
- `.agents` or `.claude` folder of its own; omp's folders follow
14
- `PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
15
- that points into one of those folders makes omp's files go there. Sync also
16
- writes the kit plugin to `~/.docks-kit/omp-plugin`. Clone once to get a
17
- consistent AI-assisted environment on supported Linux, macOS, and Windows
18
- hosts. The kit focuses on **token efficiency without sacrificing quality**.
19
- Every setting and hook minimizes token use while preserving rigorous output.
20
- When you add or edit anything, ask: *does this change reduce tokens without
21
- weakening correctness?*
9
+ Portable configuration kit for AI coding agents. The kit manages one coding harness, Oh My Pi (`omp`). Its Single Source of Truth (SoT) directory deploys to omp's user-config location through `./docks-kit sync`. Sync writes no `.agents` or `.claude` folder of its own; omp's folders follow `PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override that points into one of those folders makes omp's files go there. Sync also writes the kit plugin to `~/.docks-kit/omp-plugin`. Clone once to get a consistent AI-assisted environment on supported Linux, macOS, and Windows hosts. The kit focuses on **token efficiency without sacrificing quality**. Every setting and hook minimizes token use while preserving rigorous output. When you add or edit anything, ask: *does this change reduce tokens without weakening correctness?*
22
10
 
23
11
  omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
24
12
 
25
- docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
26
- arm64, and Windows x64. Hosts outside this matrix fail before either
27
- launcher can fall back to Bun source.
13
+ docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS arm64, and Windows x64. Hosts outside this matrix fail before either launcher can fall back to Bun source.
28
14
 
29
15
  ## Context tree
30
16
 
31
- Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load
32
- only the nodes from the root down to its working directory, so open the node
33
- for the folder you edit from this table. Edit the node, not this list, when a
34
- folder's rules change. `context-tree audit` checks this table against the
35
- AGENTS.md files on disk.
17
+ Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load only the nodes from the root down to its working directory, so open the node for the folder you edit from this table. Edit the node, not this list, when a folder's rules change. `context-tree audit` checks this table against the AGENTS.md files on disk.
36
18
 
37
19
  | Node | Governs |
38
20
  |---|---|
39
21
  | `docs/AGENTS.md` | Plan-record routing to `docs/PLAN.md` |
40
- | `cli/AGENTS.md` | Effect CLI, EngineNative sync engine, bundled docs topics, build scripts, unit and golden suites |
22
+ | `cli/AGENTS.md` | Effect CLI, EngineNative sync engine, bundled docs topics, build scripts, unit and golden suites, SoT notes |
41
23
  | `.agents/skills/AGENTS.md` | Project skills; omp reads `.agents/skills/` directly |
42
24
 
43
25
  ## Repository layout (cross-cutting)
@@ -53,41 +35,18 @@ AGENTS.md files on disk.
53
35
  | `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
54
36
  | `README.md` | Front door |
55
37
  | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
56
- | `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
38
+ | `docs/PLAN.md` | Plan pointer and project plan rules. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
57
39
  | `AGENTS.md` | This file — tool-agnostic instructions |
58
40
 
59
41
  Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
60
42
 
61
- Shared SoT notes:
62
- - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
63
-
64
- omp SoT notes:
65
- - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`. omp loads `~/.omp/agent/AGENTS.md` only into main sessions and advisors, never into task subagents (`omp://context-files.md`). So `SoT/.omp/AGENTS.md` holds only main-session rules, and a command rule that subagents need goes into a kit plugin trigger rule.
66
- - `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.
67
- - `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`.
68
- - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp 19.0.0 checks a deny rule, then a prompt rule, then its `CRITICAL_BASH_PATTERNS`, then an allow rule (`BashTool.approval` in the v19.0.0 source; `omp://approval-mode.md` still describes the 18.17.0 order, in which the critical check came before a prompt rule). A critical command that no deny or prompt rule matches gets a bare safety override, which replaces a matching allow, and omp's default `tools.approvalMode: yolo` ignores a bare override, so the command runs, in subagents too. A prompt rule asks a person, also on a critical command, but a subagent rejects every prompt. Every `rm` shape that the critical 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. The kit plugin trigger rules in `SoT/.omp/plugin/rules/` carry the agent rules for these commands. `git-safety.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 `trash *`. For a command without shell control, omp takes the first matching rule. For a command with shell control, such as `;` or `|`, each segment takes its first matching deny or prompt rule, a deny chosen for one segment wins over a prompt chosen for another segment, and an allow never matches. A segment also matches without its leading `NAME=value` words. `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 19.0.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.
69
- - `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, with no flag. 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.
70
- - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6.2-astra:xhigh`, and `modelTags.astra` (`GPT-6.2 Astra`) is visible. Astra and Fable fall back to each other through concrete selectors: `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-2:medium`, and `retry.fallbackChains.fable` holds `openai-codex/gpt-6.2-astra:xhigh`. `modelRoles.fable` is `anthropic/claude-fable-5-2:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
71
- - `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.2-sol:high`. The kit relies on omp's default `task.enableEffort: 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 the cap of the former kit value `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. Since 0.24.0 the kit sets no `task.maxEffort`, so that cap is omp's default `max`. By owner decision (0.22.22), the omp advisor is removed: the SoT has no `advisor` block, `advisor` role, or `advisor` fallback chain. The plan-lifecycle verification loop replaces a second model on every turn. A session that runs `/advisor on` takes its advisor model from the `slow` 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 and verified pin are 19.0.0, the release the kit tested on 2026-11-19: its `omp models --json` catalog lists each model selector of `modelRoles` and `retry.fallbackChains` exactly, every `SoT/.omp/config.yml` key is a key of `omp config list --json`, and `cli/test/lib/ompBashPatterns.ts` ports its approval source. The floor is doctor visibility only. Sync does not check the omp catalog, so an older omp can fuzzy-match a missing id to another model. `cli/docs/omp-models.md` records the checks.
72
- - The six Opus 5.5 roles (`default`, `slow`, `plan`, `designer`, `vision`, `task`) 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. The `astra`, `reviewer`, `fable`, and `switch_fable` rows are the exceptions: they come from v5.0.1 captures read 2026-11-18 (GPT-6.2 Astra), 2026-11-05 (GPT-6.1 Terra), and 2026-11-12 (Fable 5.2), and they compare only with other v5.0.1 figures. Opus 5.5 max has the highest v4.3.2 index in that topic, at 58. AA has measured speed and latency for every Opus 5.5 level and every GPT-6.2 Sol and GPT-6.2 Astra row in that topic. GPT-6 Luna medium is the only unmeasured speed and latency row.
73
- - `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 20-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so every entry left out is a provider omp never tries. The owner removed the seven entries that named older models (Gemini 2.5 Flash, Claude Haiku 4.5, GPT-5.6, GPT-5.5, and Grok 4.5); keep every other provider.
74
- - `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 override is keyed `gpt-6.2-astra`, the model id of the `astra` role. `ompRemovals.ts syncOmpModelRemovals` prunes the old `gpt-6-astra` block from `~/.omp/agent/models.yml` while it equals the shipped block. 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.
75
- - `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
76
- - `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. For each model that an omp role or retry chain uses, the topic keeps AA rows at `high` and `xhigh` at least, with the index version and the capture date.
77
- - `SoT/.omp/config.yml` carries only keys whose value differs from the omp default. When a kit value equals the omp default, remove the key from the SoT. Add it with its shipped value to `ompRemovals.ts OMP_RETIRED_VALUES`, because `ompYaml.ts mergeOmpConfig` is additive and only that pass prunes the deployed copy. For example, the kit ships no `compaction.thresholdTokens`, and sync prunes a deployed `-1` and the former `231200` pin. `cli/docs/omp-context.md` (topic `omp-context`) carries the reserve-based derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
78
- - 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, the `/cleanup` command, and six omp Time Traveling Stream Rules (TTSR, trigger rules) in `rules/`: `file-removal.md`, `git-safety.md`, `temp-and-background.md`, `worktree-location.md`, `literal-paths.md`, and `remote-cleanup.md`. omp's `omp-plugins` provider loads `rules/*.md` from the linked plugin root (`omp://plugin-manager-installer-plumbing.md`). Each rule has a regex `condition` scoped to `tool:bash, tool:eval` that aims at the wrong form; eval is in scope because eval code can run a shell command through `sh()`. A condition reads text, not a parsed command, so it has known false positives: a quoted command word (`echo "rm x"`, or a commit message that starts with `rm`) and eval code after the closing quote of a `sh()` string. `worktree-location.md` fires on each `git worktree add`, also at the correct path, because a condition cannot read `$XDG_DATA_HOME` or the home directory. omp aborts the matching tool call before it runs, injects the rule, and retries (`omp://ttsr-injection-lifecycle.md`). Each rule has `repeatMode: always`: it fires at each later wrong form, but not on the retry that its own reminder starts. The rules reach subagents and cost no prompt tokens until they fire. They teach the correct form; the `bash.patterns` denies still enforce. omp tests each condition on the partial argument buffer after each streamed delta, so a condition must not match a prefix of a correct command: it needs a delimiter after each token it checks, never the end anchor `$`. The buffer is the argument JSON text, the intent field `i` can come before or after `command`, and a provider can put JSON white space around the colon (`{"command": "ls"}`). So each condition starts its match with the forward key prefix `"(?:command|code)"\s*:\s*"[^"\\]*?` and an escape loop that takes up to 8 escape pairs per step; `cli/docs/command-guards.md` shows the full prefix. Only the key prefix is sure to stay inside the `command` or `code` string. The rest of a condition can cross the closing quote: the `Bun.file` condition of `file-removal.md` matches `{"code":"Bun.file(","i":").delete("}`. omp's `Matched:` excerpt is a bounded window around the match start: up to 60 characters before it, and a long match is cut at 180 characters from its start, so in a long call the trigger can be outside the excerpt. A scan stops at an unescaped `"` and at a newline (`\n`), a tab (`\t` in the buffer) counts as shell white space, and a scan that looks for an option stops at a ` -- ` word. omp runs each test on its main thread, in JavaScriptCore. Up to 0.22.29, each condition started with an unbounded lookbehind, which walked back over the buffer from every position. A 20 KB call then froze the session for seconds, and past the JavaScriptCore match limit the rule did not fire. So never start a condition with an unbounded lookbehind. Make each scan after a command start one lazy walk that stops at its first event: `(?=(?<w>[\s\S]*?)(?=EVENT)BOUNDARY)\k<w>`. The events are the flag of the condition, a terminator, the end of the run, and the next command start, each at a real token boundary. The lookahead does not backtrack after it matches, so the walk stays frozen. The stop at the next command start keeps a line that repeats a command start linear. Never put a group loop inside a lookaround over text of unbounded length, because JavaScriptCore then keeps each loop step until the match attempt ends and drops out of the JIT. omp tests open buffers that stop before the closing quote, so a scan must not rely on that quote to stop. `cli/test/unit/ompTriggerRules.test.ts` pins every condition through bash and through Python and JavaScript eval `sh()` calls, in the compact and the spaced JSON layouts, with some rows in the pretty layout and trigger words in the intent before and after the command. It checks that each condition has a wrong row that fires it and that each rule has `repeatMode: always`. Its shape guard checks only the key prefix and that no `|` stands outside every group. Its backstop runs `cli/test/lib/ompTriggerBackstop.ts` under Bun and tests the measured input families for linear time: a time budget, a fire check, scaling with the JIT off, and dense and head-and-run lines with the JIT on, in bash, open bash, and Python. A condition can still backtrack on a run that no generator holds, so a new condition needs a new family when its shape is new. Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts` after each condition change; it runs both guards. When you rewrite a condition, run the old and the new condition on each buffer of the test table and compare the results. `cli/docs/command-guards.md` (topic `command-guards`) lists the rules, the false positives, and the input families that a forward key prefix alone does not make linear. 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.
79
- - By owner decision (0.24.0), `astGrep.enabled` and `checkpoint.enabled` are `true`, so omp offers the `ast_grep` tool and the `checkpoint` and `rewind` tools. `rewind` restores only the conversation, and a rule line in `SoT/.omp/AGENTS.md` says so. The memory backend, `autolearn.enabled`, and `prewalk.enabled` stay off. Every other omp 19.0.0 feature keeps its omp default. The owner also returned 18 kit overrides to the omp defaults, for example `task.agentIdleTtlMs` (omp parks an idle subagent after 7 minutes) and `browser.idleCloseSec`. `OMP_RETIRED_VALUES` prunes each deployed key while it still holds the value that the kit shipped. `cli/docs/omp-context.md` lists the 18 keys, the kept overrides, and why `issue://` and `pr://` still work with `github.enabled` at its default `false`.
80
- - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp `remote-cleanup.md` trigger rule, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH, a database client, or a provider CLI such as `wrangler`, `vercel`, `kubectl`, `aws`, 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.
81
- - 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.
82
- - omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
83
-
84
- For the omp SoT layout (`SoT/.omp/`), see that directory.
43
+ SoT notes (the shared prompt authorization, the omp deploy targets, the config and model merges, the retired inventories, the role map, the kit plugin sync, and the cleanup scope): `cli/AGENTS.md` (`### SoT notes`).
85
44
 
86
45
  ## Engineering rules
87
46
 
88
47
  - **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing, kit store, module boundaries): `cli/AGENTS.md`.
89
48
  - **One sync.** `./docks-kit sync` deploys the omp SoT and takes no positional target. Combine it with `--dry-run`, `--skip-plugin-refresh` (install missing omp plugins without refreshing existing ones), and `--verbose`.
90
- - **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. The exceptions are the omp retired inventories: `ompRemovals.ts` force-prunes retired kit-owned keys, `bash.patterns` rules, and model blocks on every sync (see the omp SoT notes above). Sync has no removal flag.
49
+ - **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. The exceptions are the omp retired inventories: `ompRemovals.ts` force-prunes retired kit-owned keys, `bash.patterns` rules, and model blocks on every sync (see the omp SoT notes in `cli/AGENTS.md`). Sync has no removal flag.
91
50
  - **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.
92
51
  - **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.
93
52
  - **Regenerate the payload.** After `SoT/` 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.
@@ -104,8 +63,8 @@ For the omp SoT layout (`SoT/.omp/`), see that directory.
104
63
 
105
64
  - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
106
65
  - 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.
107
- - **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`.
108
- - **Exemptions: the kit's own package 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. The existing omp marketplace plugin installs have no manifest pin: 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.
66
+ - **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version, except the exemption 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`.
67
+ - **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 `@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. Any new install surface, a new marketplace or plugin source included, needs a manifest pin first.
109
68
  ## Testing
110
69
 
111
70
  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` and `bun run smoke:native`.
@@ -126,87 +85,14 @@ Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citat
126
85
 
127
86
  **Vendored `unslop`.** The kit never runs the skills CLI. Only a maintainer refreshes the vendored `.agents/skills/unslop/` copy, with `npx skills@1.7.0 add cursor/plugins -s unslop -y -a universal`. The skills CLI 1.7.0 installs the `universal` agent into the project path `.agents/skills/`, which omp reads.
128
87
 
88
+ ## Kit plugin content
89
+
90
+ `SoT/.omp/plugin/` holds skills at `skills/<name>/SKILL.md`, task agents at `agents/<name>.md`, and the extensions that `package.json` `omp.extensions` names. It ships the 32 docks and plan-lifecycle skills, the `workspace-hygiene` skill, the `code-reviewer` and `plan-reviewer` agents, the `hygiene`, `verify-gate`, and `context-tree-nudge` extensions, the trigger rules in `rules/`, and the `/cleanup` command. A skill reports a problem in DocksDocks/public. `bun run check` checks this content with four tests in `cli/test/unit/plugin/`: `skills.test.ts` (layout and name, frontmatter, report section, shared copies, references, durable anchors, transform guard, trigger collisions, score floor), `contentHash.test.ts`, `agents.test.ts` (agent rules, score floor), and `extensions.test.ts` (each entry imports and has a default function export).
91
+ After a skill edit, run `bun cli/scripts/skill-content-hash.ts --write` to refresh its `metadata.content_hash` and `metadata.updated`; `--check` names each stale skill. The check code and its data (floors, report section, shared-copy groups, transform list) are in `cli/scripts/pluginContent/`.
92
+
129
93
  ## Plans
130
94
 
131
- Use direct implementation for one clear, reversible, low-risk local diff with one
132
- bounded acceptance path; it creates no plan issue, reviewer, or automatic
133
- commit. Use a canonical plan for explicit planning, multi-commit or
134
- cross-repository work, cold handoff, an unresolved decision, a cross-subsystem or
135
- public-contract change, security-sensitive or destructive work, or any
136
- non-`local` effect.
137
-
138
- <constraint>
139
- The plan record is a GitHub issue. Its body starts with
140
- `<!-- plan-contract: v4 -->`, followed by one blank line and seven `##`
141
- sections. It has no frontmatter. GitHub owns the title, open-work phase, owner,
142
- timestamps, and completion. The repository tracks no plan markdown.
143
- Three skills own the workflow. `plan-workspace` maintains the workspace.
144
- Main-context `plan-manager` runs six phases: decide, draft, research, plan
145
- review, implement, and code review. It uses bounded repair and fresh re-review
146
- in both review phases, then archives. Internal `plan-reviewer` returns one
147
- readable pre-implementation verdict block per round. Two read-only reviewer
148
- wrappers ship: `plan-reviewer` and `code-reviewer`.
149
- 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.
150
- </constraint>
151
-
152
- After the marker and blank line, the record carries exactly seven sections.
153
- They appear once each in this order: `## Goal`, `## Research`, `## Steps`,
154
- `## Acceptance`, `## Do not touch`, `## Open questions`, and
155
- `## Verification Results`. `## Goal` carries exactly one mode line.
156
- Open-work phase is `drafting`, `planned`, `ongoing`, or `blocked`.
157
- Every plan carries `plan`. A `plan:<phase>` label stores the open phase.
158
- A blocked plan starts `## Open questions` with `Blocked: <one-line reason>`.
159
- GitHub `state` and `stateReason` determine closed status. Review records live
160
- only in issue comments. Each reviewer returns one markdown block.
161
- The manager posts that block as one issue comment. The latest trusted eligible
162
- comment per review kind wins. Its author must equal the plan's sole assignee.
163
- Both review phases use fresh inputs for each round. They stop on
164
- pass. Ask the user to continue or block when a round makes no progress, the
165
- same finding returns after a repair, round 5 does not pass, or dispatch fails
166
- again without a relevant change. If no answer is available, record the reason
167
- and block. A yolo run uses the round ceiling of the contract's Yolo runs
168
- section instead.
169
- A plan-review `blocked` verdict routes its user-only decision through
170
- `## Open questions` and `ask`.
171
-
172
- The record carries no hash, permit, run identity, lock, or bundle, and the
173
- `plan.mjs` shipped inside the installed `plan-lifecycle` plugin is the only
174
- lifecycle tool. An `export` writes the sha256 of the body it copied beside the
175
- copy so a stale copy cannot revert the record; that digest detects staleness and
176
- authorizes nothing. Routine plan issue publication, implement-start linked
177
- branch creation, commits, normal pushes, and the closing pull request carry the
178
- settled mode's authorization and need no repeated prompt. Before any branch
179
- checkout, including `gh issue develop --checkout`, require
180
- `git status --porcelain` to be empty. If it is dirty, never stash, move, or
181
- commit ambient work; set the plan `blocked` and name the dirty paths, or use an
182
- authorized clean worktree.
183
- Immediately after setting the plan `ongoing`, every `gh issue develop` call uses
184
- `--repo`; the manager reuses a linked branch or creates one with
185
- `--base <default> --checkout`, then re-lists and recovers after failure.
186
- Implementation stops when no linked branch can be verified; there is no local
187
- fallback. After the checks policy passes, the manager asks immediately before
188
- merge. Without a fresh `Merge now` answer, it leaves the pull request and issue
189
- open. `plan.mjs archive` verifies the latest trusted code-review result and
190
- merged closing pull request after landing.
191
-
192
- Every Steps row carries an `Effect` of exactly
193
- `local|probe|production_access|publish|push|release|deploy`. A step whose
194
- `Effect` is not `local` requires an in-session `ask` confirmation immediately
195
- before it runs; when `ask` is unavailable the step is set `blocked` and the plan
196
- reason becomes the first `## Open questions` line, `Blocked: <reason>`.
197
- Persisted effects record intent only. Routine issue publication and landing
198
- actions are outside the Steps table.
199
- 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.
200
-
201
- 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.
202
-
203
- No plan markdown is tracked. The pre-GitHub records under
204
- `docs/plans/finished/` were deleted; `git log -- docs/plans/finished/` recovers
205
- them as history, and no lifecycle command restores them. The complete contract
206
- lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it.
207
-
208
- Plugin-internal work (skills, commands, agents) belongs in each plugin's
209
- own repo, not here.
95
+ Read `docs/PLAN.md` before plan work; `docs/AGENTS.md` holds the docs-folder rules. The canonical contract is `skill://plan-manager/references/plan-contract.md` in the docks-kit kit plugin. Use `plan-workspace` for setup, main-context `plan-manager` for the six phases, and read-only `plan-reviewer` and `code-reviewer` wrappers for review. Use direct implementation only for a clear, reversible, low-risk local diff with one bounded acceptance path. Otherwise follow the plan-manager decision. Plan issues are the live records. Leave `docs/plans/finished/` frozen.
210
96
 
211
97
  ## Notes for nested overrides
212
98
 
@@ -223,5 +109,4 @@ cd ~/projects/public
223
109
  ./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
224
110
  ```
225
111
 
226
- On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout
227
- commands.
112
+ On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout commands.
package/README.md CHANGED
@@ -102,6 +102,31 @@ Full reference: `docks-kit docs flags`.
102
102
  omp plugin `docks-kit-omp` exposes these as tools, reminds the agent of
103
103
  what it created, and runs the sweep at most once per 12 hours.
104
104
 
105
+ ## Kit plugin
106
+
107
+ Sync writes the kit plugin `docks-kit-omp` to `~/.docks-kit/omp-plugin` and
108
+ links it into omp. The kit plugin content comes from `SoT/.omp/plugin/`:
109
+
110
+ - **Skills** — the 32 docks and plan-lifecycle skills, for example
111
+ `plan-manager`, `plan-workspace`, `code-review`, `security`, and
112
+ `refactor`, plus the `workspace-hygiene` skill.
113
+ - **Agents** — the `code-reviewer` and `plan-reviewer` task agents.
114
+ - **Extensions** — `verify-gate` checks that each `git commit` carries a
115
+ `Verified:` trailer, `context-tree-nudge` names the context-tree node of
116
+ each edited file, and `hygiene` gives the agent cleanup tools and
117
+ reminders.
118
+ - **Rules and commands** — six trigger rules that teach the safe form of a
119
+ risky command, and the `/cleanup` command.
120
+
121
+ The kit plugin replaces the former `docks` and `plan-lifecycle` plugins of
122
+ the `docks` marketplace. `docks-kit sync` uninstalls their user-scope installs
123
+ when it can read the omp plugin inventory, and then removes the `docks`
124
+ marketplace when no uninstall failed and it can read the marketplace registry.
125
+ It only warns about a project-scope install, with the manual command. When a
126
+ read fails, sync warns and skips that step, and a later sync tries again.
127
+ Report a problem with a skill, an agent, or the kit in
128
+ [DocksDocks/public](https://github.com/DocksDocks/public/issues).
129
+
105
130
  ## Repository map
106
131
 
107
132
  | Path | Purpose |
@@ -113,7 +138,7 @@ Full reference: `docks-kit docs flags`.
113
138
  | `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
114
139
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
115
140
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
116
- | `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
141
+ | `docs/PLAN.md` | Plan pointer and project plan rules; plans are GitHub issues |
117
142
  | `AGENTS.md` | Agent-facing engineering rules |
118
143
 
119
144
  ## Platform support
@@ -108,9 +108,10 @@ worktree and an upstream; `git pull --ff-only`, then re-runs
108
108
  `bun install --frozen-lockfile` when the pull changed `bun.lock` or
109
109
  `package.json`); a kit home under `node_modules` is a global package
110
110
  (`bun add -g` / `npm install -g docks-kit@latest`). The chained sync is a
111
- plain flag-less `docks-kit sync`. It refreshes plugin marketplaces and
112
- installed plugins even when the kit is already current. Pass `--no-sync`, then
113
- run `docks-kit sync --skip-plugin-refresh` to skip the refresh-only work.
111
+ plain flag-less `docks-kit sync`. It also refreshes plugins, even when the kit
112
+ is already current: it moves `pi-intercom` to its pinned version. Pass
113
+ `--no-sync`, then run `docks-kit sync --skip-plugin-refresh` to keep a present
114
+ `pi-intercom` at its installed version.
114
115
  A compiled binary inside a checkout updates the checkout; on the next invocation
115
116
  the launcher bypasses that now-stale binary and uses updated source until rebuilt.
116
117
  Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
@@ -128,14 +128,15 @@ What omp's settings catalog establishes about these roles:
128
128
  model for every reviewer. `task.agentServiceTierOverrides` sets the same four
129
129
  agents to `inherit`, so they take the live tier of the main session for each
130
130
  provider. "OpenAI fast mode" below describes how that tier changes. The bundled
131
- `reviewer` and `security-reviewer` agents ship with omp, and the
132
- `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`.
131
+ `reviewer` and `security-reviewer` agents ship with omp, and the kit plugin
132
+ `docks-kit-omp` ships `code-reviewer` and `plan-reviewer`.
133
133
  `retry.fallbackChains.reviewer` holds `anthropic/claude-opus-5-5:high`, and
134
134
  `retry.fallbackChains.task` holds `openai-codex/gpt-6.2-sol:high`; both are
135
135
  cross-vendor fallbacks.
136
136
 
137
137
  The review benchmark of DocksDocks/public#130 ran on 2026-11-05. It used 24
138
- held-out cases of the DocksDocks/docks `review-benchmark` skill, 2 runs each.
138
+ held-out cases of the `review-benchmark` skill, 2 runs each. The cases came
139
+ from DocksDocks/docks, the source repository of that skill at the time.
139
140
  It compared `gpt-6.1-sol` and `gpt-6.1-terra` at `high`, each on the `default`
140
141
  and `priority` tiers. The user set the effort `high`; the benchmark chose the
141
142
  model. `gpt-6.1-terra` on `default` let the fewest known defects escape (34.90
@@ -25,83 +25,53 @@ retired in 0.22.8), config.yml keys whose deployed value still equals the value
25
25
  ship, `providers.webSearchOrder` at any value, and the retired
26
26
  `providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
27
27
  it still matches the shipped block.
28
- Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
29
- registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
30
- through `omp plugin`, and `pi-intercom` is installed at its
31
- `SoT/toolchain.json` pin. Inventory comes from `omp plugin list --json`, where a
32
- marketplace row counts as installed only when its `scope` is `user`, so a repeat
33
- run is a no-op and a project-only row still installs. When just the legacy
34
- config-root registry lists `docks`, omp copies it forward itself: the sync runs
35
- `marketplace update`, or the read-only `marketplace list` under
36
- `--skip-plugin-refresh`, which keeps installs but fetches nothing. After a
37
- plugin operation, the sync reads the inventory again and prints one line that
38
- names each plugin with its version change, for example
39
- `omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
28
+ Directories are mode 0700 and files mode 0600. Then the plugin pass reads the
29
+ inventory from `omp plugin list --json`, tries to retire the former marketplace
30
+ plugins (user-scope installs only; see below), installs `pi-intercom` at its
31
+ `SoT/toolchain.json` pin, and links the kit plugin `docks-kit-omp`.
40
32
 
41
- omp deletes the previous plugin folder on `omp plugin upgrade`. A running omp
42
- session then loses the plugin agents of that folder. A test on omp 18.16.0
43
- showed that `/reload-plugins` brings the agents back, and that `skill://`
44
- resolves to the new folder (#139). The omp marketplace docs still ask for a
45
- restart for hooks, extension modules, and non-MCP tools. For each marketplace
46
- upgrade that changed the version, the sync prints a warning, for example
47
- `omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents until they run /reload-plugins and read its skills again through skill:// (restart omp instead when the plugin ships hooks, extension modules, or non-MCP tools).`
48
- The next step then says
49
- `Run /reload-plugins in each running omp session, then read each plugin skill again through skill://. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools.`
50
- A version-changing upgrade does not set the restart trigger. Each other plugin
51
- operation sets it: an install, a reinstall at the same version, an npm install,
52
- or a link. A changed kit plugin file or omp config file also sets it. The
53
- restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
54
- then prints next to the upgrade rule.
33
+ The kit plugin now ships the docks and plan-lifecycle skills, the
34
+ `code-reviewer` and `plan-reviewer` agents, and the `verify-gate` and
35
+ `context-tree-nudge` extensions. So sync installs no plugin from the `docks`
36
+ marketplace. Each real sync tries to retire the former marketplace plugins.
37
+ When the inventory cannot be read, it warns and skips this step; a later sync
38
+ tries again. Otherwise:
55
39
 
56
- The sync also writes one event file for each such upgrade into the upgrade log
57
- `~/.cache/docks-kit/omp-plugin-upgrades/` (folder 0700, files 0600). The file
58
- name is `<finishedAt ms>-<random>.json`, and the file holds
59
- `{"version":1,"id":"<id>","before":"<v>","after":"<v>","finishedAt":"<ISO time>"}`.
60
- `finishedAt` is the time just after the upgrade command returned. Each sync
61
- writes only new files, through a temporary name and a rename, so concurrent
62
- syncs keep all events. Then it removes the oldest files beyond the newest 100.
40
+ - For each of `docks@docks` and `plan-lifecycle@docks` with a `scope: "user"`
41
+ inventory row, it runs `omp plugin uninstall --scope user <id>`.
42
+ - For each `scope: "project"` row of these ids, it changes nothing in that
43
+ project and warns
44
+ `omp plugin <id> is installed at project scope and docks-kit no longer ships it; run from that project: omp plugin uninstall --scope project <id>`.
45
+ - When no user uninstall failed, it runs `omp plugin marketplace remove docks`
46
+ if the active registry (`<data root>/marketplaces.json`) lists `docks`, or
47
+ if no active registry exists and the legacy config-root registry lists it.
48
+ omp copies the legacy registry forward only when no active registry exists,
49
+ so a legacy entry beside an active registry is stale and starts no command.
50
+ - A failed uninstall or removal goes to the failure ledger with the manual
51
+ command, for example
52
+ `omp plugin operation failed for docks@docks: <detail>; run manually: omp plugin uninstall --scope user docks@docks`.
53
+ - When the inventory cannot be read, the sync warns
54
+ `omp plugin inventory unavailable — retirement of the docks marketplace plugins skipped until the next sync; pi-intercom and the kit plugin take the full refresh path`.
55
+ - The sync removes the folder `~/.cache/docks-kit/omp-plugin-upgrades/` of the
56
+ retired plugin upgrade log when it exists.
63
57
 
64
- If the inventory read after the operations fails, the sync cannot see the new
65
- versions. It then warns
66
- `omp plugin versions could not be read after the upgrade — each upgraded plugin counts as changed`.
67
- Each upgrade of a present marketplace plugin then counts as a change. It gets
68
- the warning and an event with the after version `unknown`, for example
69
- `docks@docks 0.21.1 -> unknown`.
58
+ `--skip-plugin-refresh` does not skip the retirement or the kit plugin link. It
59
+ only keeps a present `pi-intercom` at its installed version. A repeat run after
60
+ a successful retirement runs no uninstall and no removal.
70
61
 
71
- A failed write or prune of the upgrade log does not fail the sync, because it
72
- is not a harness CLI operation. A failed write warns
73
- `omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades; give each of them the advice above`.
74
- The summary line, the upgrade warnings, and the next steps stay. A failed prune
75
- keeps the new events and warns
76
- `omp plugin upgrade log not pruned: <error> — it can keep more than 100 event files`.
62
+ After a plugin operation, the sync prints one line that names each operation,
63
+ for example
64
+ `omp plugins synced: docks@docks uninstalled, plan-lifecycle@docks uninstalled, docks marketplace removed, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
65
+ Each uninstall sets the restart next step
66
+ `Restart omp to load any refreshed plugins, skills, or tools.`, because the
67
+ retired plugins ship extensions, and omp loads extensions only at startup. An
68
+ npm install, a link, and a changed kit plugin file or omp config file also set
69
+ it.
77
70
 
78
- The kit plugin extension `pluginUpgrades.ts` reads the upgrade log. In each
79
- tool result of a main omp session, it takes the events that finished after
80
- its omp process started. It adds one reminder for the events that the session
81
- did not get before. The reminder names each plugin with its version change. It
82
- says that the plugin agents of the session may fail. It tells the agent to ask
83
- the user to run `/reload-plugins`. It then tells the agent to read each plugin
84
- skill again through `skill://` before it runs a skill script. It asks for a
85
- restart instead when an upgraded plugin ships hooks, extension modules, or
86
- non-MCP tools. A folder or file that the extension cannot read gives no
87
- reminder for that tool result. The next tool result reads it again.
88
- These limits apply:
89
-
90
- - omp imports extension modules only at startup. An omp process that started
91
- before a sync deployed `pluginUpgrades.ts` did not load it. Its sessions get
92
- no reminder, also for the upgrades of that sync.
93
- - An upgrade that `docks-kit sync` did not run gives no reminder, for example
94
- `omp plugin upgrade` by hand.
95
- - The warning, the next step, and the reminder assume that the session loaded
96
- the user-scope install. omp keeps an old cache folder that a known project
97
- registry still uses. So a session on a project-scope install keeps its
98
- folder. For this reason, the reminder says "may".
99
- - An omp process that started during the upgrade can get a reminder that it
100
- does not need. A reload or a restart is harmless.
101
- - The log keeps the newest 100 events. A session that stays idle through more
102
- than 100 later upgrades loses the oldest ones.
103
-
104
- A dry run invokes no omp subcommand and writes no upgrade event.
71
+ A dry run invokes no omp subcommand. It prints
72
+ `[dry-run] omp plugin uninstall --scope user docks@docks` and the same line
73
+ for `plan-lifecycle@docks`, and
74
+ `[dry-run] omp plugin marketplace remove docks` when a registry lists `docks`.
105
75
 
106
76
  Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
107
77
  plus directory probes, so a dry run still runs no omp subcommand. The agent
@@ -120,6 +90,7 @@ into `<agent directory>/intercom`. Otherwise it goes into
120
90
  ## Additive by default
121
91
 
122
92
  Sync has no removal flag. A key, plugin, or file that only the user added
123
- stays. Two passes remove kit content on every sync: the `ompRemovals.ts`
124
- retired-key inventory above, and the kit plugin pass, which removes stale
125
- files from the kit-owned `~/.docks-kit/omp-plugin`.
93
+ stays. Three passes remove kit content on every sync: the `ompRemovals.ts`
94
+ retired-key inventory above, the kit plugin pass, which removes stale files
95
+ from the kit-owned `~/.docks-kit/omp-plugin`, and the retirement of the former
96
+ marketplace plugins above, which earlier kit versions installed.
@@ -35,11 +35,10 @@ Every kit-driven package install from npm, GitHub releases, or
35
35
  `omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
36
36
  floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
37
37
  the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
38
- The existing omp
39
- marketplace plugins have no manifest pin: sync installs and refreshes them at
40
- the version that their marketplace publishes (see `sync-layers`). Any new
41
- install surface, a new marketplace or plugin source included, needs a
42
- manifest pin first.
38
+ The kit installs no omp marketplace plugin: the kit plugin ships from this
39
+ repository, and sync tries to retire the user-scope installs of the former `docks` marketplace plugins (see
40
+ `sync-layers`). Any new install surface, a new marketplace or plugin source
41
+ included, needs a manifest pin first.
43
42
 
44
43
  The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
45
44
  end with `bun add -g docks-kit@latest` because a global installer that pinned
@@ -202,8 +202,8 @@ const updateCheckout = (home: string, skipSync: boolean) =>
202
202
  if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`);
203
203
  const after = git(home, ["rev-parse", "HEAD"]).out;
204
204
 
205
- // A current kit still syncs: the plugin passes deliver marketplace and
206
- // plugin updates that move independently of the kit's own version.
205
+ // A current kit still syncs: the sync repairs drift of the deployed files
206
+ // and plugins, for example a pi-intercom install that left its pin.
207
207
  const changed = before !== after;
208
208
  if (changed) {
209
209
  const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out;
@@ -312,6 +312,6 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
312
312
  }),
313
313
  ).pipe(
314
314
  Command.withDescription(
315
- "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugin marketplaces and plugins, even when the kit was already current (--no-sync to skip).",
315
+ "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugins, even when the kit was already current (--no-sync to skip).",
316
316
  ),
317
317
  );
@@ -39,8 +39,7 @@ shell engine was removed after the `bash-engine-final` tag.
39
39
  the whole files, merges `config.yml` and runs the retired-key removals on
40
40
  the merged result, merges `models.yml` and runs its removals, writes the
41
41
  intercom configuration, materializes the kit plugin, and only then runs the
42
- marketplace and plugin passes, because the plugin pass links the kit plugin
43
- directory.
42
+ plugin pass, because the plugin pass links the kit plugin directory.
44
43
  - **One pipeline.** Sync runs only the omp pipeline, which is serial.
45
44
  `syncConcurrency.ts` `runBounded` stays for the parallel probes of `tidy`
46
45
  and the tidy report.
@@ -119,9 +118,9 @@ pipeline settles, also on dry-run. When the pipeline rejects, `syncDispatch.ts`
119
118
  `engineSync` skips the block and prints only the `--- Failures ---` ledger.
120
119
  The block starts with a `Repo:` line and adds the `omp:` and `omp plugins:`
121
120
  inventory lines. Dry-run leaves out the `omp plugins:` line. Next-step advice
122
- lines print only when their trigger changed this run (an omp plugin upgraded
123
- → `/reload-plugins` line; omp files changed → restart line) or under
124
- `--verbose`.
121
+ lines print only when their trigger changed this run (an omp plugin operation,
122
+ such as the uninstall of a retired marketplace plugin, or a changed omp file →
123
+ restart line) or under `--verbose`.
125
124
 
126
125
  ### Platform seam
127
126
 
@@ -178,7 +177,7 @@ active logger binding.
178
177
  | `syncConcurrency.ts` | input-ordered bounded pool (`runBounded`) for the tidy probes |
179
178
  | `../payload.ts` | generated text payload reads and presentation-only source labels |
180
179
  | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the omp pipeline and direct toolchain ensure |
181
- | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompMarketplace.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, marketplace, plugin, and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
180
+ | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, plugin (with the marketplace-plugin retirement), and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
182
181
  | `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
183
182
  | `modes.ts` | direct `toolchain` mode |
184
183
  | `jq.ts` | the `Json` value type, object narrowing, jq-compatible codepoint ordering, and a parse that yields `undefined` instead of throwing |
@@ -22,8 +22,6 @@ export interface Ctx {
22
22
  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
23
23
  readonly nextStepTriggers: {
24
24
  ompRestart: boolean;
25
- /** A marketplace plugin upgrade changed a version, so running omp sessions lost its folder. */
26
- ompPluginUpgraded: boolean;
27
25
  };
28
26
  /** Harness-CLI operations that failed this run; a non-empty list fails the sync. */
29
27
  readonly failures: Array<string>;
@@ -56,7 +54,6 @@ export function makeCtx(services: EngineServices, options: CtxOptions): Ctx {
56
54
  services,
57
55
  nextStepTriggers: {
58
56
  ompRestart: false,
59
- ompPluginUpgraded: false,
60
57
  },
61
58
  failures: [],
62
59
  };
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Failure ledger for harness-CLI operations. A kit-managed marketplace or
3
- * plugin command that exits non-zero is recorded here so engineSync can list
2
+ * Failure ledger for harness-CLI operations. A kit-managed plugin or
3
+ * marketplace command that exits non-zero is recorded here so engineSync can list
4
4
  * it and exit non-zero instead of reporting a clean sync.
5
5
  */
6
6
  import type { Ctx } from "./index";
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * The `omp` child processes of a sync. Every `omp` command that the
3
- * marketplace and plugin passes run starts through `spawnOmp`, so each child
3
+ * plugin pass runs starts through `spawnOmp`, so each child
4
4
  * writes into the data root that the sync locked.
5
5
  */
6
6
  import { spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec";