docks-kit 0.23.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.
Files changed (59) hide show
  1. package/AGENTS.md +22 -138
  2. package/README.md +38 -23
  3. package/cli/docs/command-guards.md +5 -3
  4. package/cli/docs/flags.md +11 -29
  5. package/cli/docs/install.md +5 -4
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +22 -15
  8. package/cli/docs/overview.md +5 -8
  9. package/cli/docs/sync-layers.md +55 -83
  10. package/cli/docs/toolchain.md +7 -8
  11. package/cli/src/argv.ts +0 -4
  12. package/cli/src/argvValidate.ts +2 -9
  13. package/cli/src/commands/docs.ts +2 -2
  14. package/cli/src/commands/omp.ts +1 -1
  15. package/cli/src/commands/scratch.ts +1 -1
  16. package/cli/src/commands/sync.ts +3 -24
  17. package/cli/src/commands/tidy.ts +1 -1
  18. package/cli/src/commands/update.ts +3 -3
  19. package/cli/src/engine-native/DESIGN.md +24 -35
  20. package/cli/src/engine-native/deps.ts +2 -7
  21. package/cli/src/engine-native/engineCtx.ts +3 -31
  22. package/cli/src/engine-native/failures.ts +2 -2
  23. package/cli/src/engine-native/index.ts +2 -2
  24. package/cli/src/engine-native/kitDb.ts +21 -37
  25. package/cli/src/engine-native/ompChild.ts +1 -1
  26. package/cli/src/engine-native/ompFastMode.ts +1 -1
  27. package/cli/src/engine-native/ompKitPlugin.ts +7 -16
  28. package/cli/src/engine-native/ompOverlay.ts +1 -1
  29. package/cli/src/engine-native/ompPlugins.ts +205 -221
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +6 -15
  33. package/cli/src/engine-native/os/posix.ts +0 -1
  34. package/cli/src/engine-native/os/types.ts +0 -4
  35. package/cli/src/engine-native/os/windows.ts +0 -1
  36. package/cli/src/engine-native/parseArgs.ts +1 -61
  37. package/cli/src/engine-native/parseHelp.ts +1 -6
  38. package/cli/src/engine-native/scratch.ts +1 -1
  39. package/cli/src/engine-native/sharedTypes.d.ts +1 -1
  40. package/cli/src/engine-native/syncConcurrency.ts +3 -3
  41. package/cli/src/engine-native/syncDispatch.ts +26 -92
  42. package/cli/src/engine-native/toolchain.ts +1 -5
  43. package/cli/src/generated/sotPayload.ts +339 -17
  44. package/cli/src/main.ts +3 -7
  45. package/cli/tsconfig.json +1 -0
  46. package/package.json +2 -2
  47. package/cli/src/checklistPrompt.ts +0 -464
  48. package/cli/src/commands/harnesses.ts +0 -77
  49. package/cli/src/commands/skills.ts +0 -40
  50. package/cli/src/engine-native/harnesses.ts +0 -138
  51. package/cli/src/engine-native/ompMarketplace.ts +0 -140
  52. package/cli/src/engine-native/skillsInstall.ts +0 -135
  53. package/cli/src/engine-native/skillsLinks.ts +0 -216
  54. package/cli/src/engine-native/skillsManifest.ts +0 -36
  55. package/cli/src/engine-native/skillsPrune.ts +0 -117
  56. package/cli/src/engine-native/skillsRecords.ts +0 -138
  57. package/cli/src/engine-native/skillsSync.ts +0 -57
  58. package/cli/src/manifests.ts +0 -53
  59. package/cli/src/terminalCells.ts +0 -191
@@ -1,7 +1,9 @@
1
1
  # omp context and compaction
2
2
 
3
3
  This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
4
- and what omp's reserve-based default computes on each model lane.
4
+ and what omp's reserve-based default computes on each model lane. It also
5
+ records the omp 19.0.0 tools that the kit turns on and the kit overrides that
6
+ 0.24.0 returned to the omp defaults.
5
7
 
6
8
  ## How omp resolves the trigger
7
9
 
@@ -100,13 +102,13 @@ No current role model has a window below 272,000, so the hazard was latent
100
102
  rather than live. Not pinning removes it entirely, including for any future
101
103
  model with a smaller window.
102
104
 
103
- ## Idle compaction is a kit-set value
105
+ ## Idle compaction is off
104
106
 
105
- `SoT/.omp/config.yml` sets `compaction.idleEnabled: true`. The omp default is
106
- `false` in omp 18.4.4 through 18.10.4. Idle compaction fires below the
107
- reserve-based trigger on both lanes. A compaction whose reason is `idle`
108
- skips the progress guard. Keep the key. The merge is additive, so a dropped
109
- key turns idle compaction off on fresh installs.
107
+ Up to 0.23.0, `SoT/.omp/config.yml` set `compaction.idleEnabled: true`. In
108
+ 0.24.0 the owner returned the key to the omp default `false` (omp 18.4.4
109
+ through 19.0.0). Sync prunes a deployed `true` that the kit shipped, so idle
110
+ compaction is off. With the default threshold settings, only the
111
+ reserve-based trigger starts a compaction.
110
112
 
111
113
  ## Related settings left at their omp defaults
112
114
 
@@ -119,3 +121,73 @@ key turns idle compaction off on fresh installs.
119
121
 
120
122
  Every row records a decision to leave the omp default in place. None of these
121
123
  keys carries a kit value that differs from the default omp already applies.
124
+
125
+ ## omp 19.0.0 tools and returned overrides
126
+
127
+ The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
128
+
129
+ ### Tools that the kit turns on
130
+
131
+ - `astGrep.enabled: true` gives the `ast_grep` tool. It searches code by its
132
+ syntax tree (AST), on the local disk only.
133
+ - `checkpoint.enabled: true` gives the `checkpoint` and `rewind` tools.
134
+ `checkpoint` marks the start of an investigation. `rewind` replaces the
135
+ transcript after that mark with a short report. It restores no file, git
136
+ state, artifact, or process, and a rule line in `SoT/.omp/AGENTS.md` says
137
+ so. A subagent gets the two tools only when its tool list asks for one of
138
+ them.
139
+
140
+ The memory backend (`memory.backend: off`), `autolearn.enabled`, and
141
+ `prewalk.enabled` stay off. All three are off by default, so the SoT has no
142
+ key for them. Every other omp 19.0.0 feature keeps its omp default, for
143
+ example context notes, `security_scan`, `task.crossInstance`,
144
+ `mcp.evalNamespaces`, and cache warming. The advisor stays removed (0.22.22).
145
+
146
+ ### Overrides returned to the omp defaults
147
+
148
+ The SoT no longer ships these 18 keys. `ompRemovals.ts OMP_RETIRED_VALUES`
149
+ records each key with its old kit value. Sync prunes a deployed key only
150
+ while it holds that value, so a value that you changed stays.
151
+
152
+ | Key | Old kit value | omp 19.0.0 default |
153
+ |---|---|---|
154
+ | `task.maxConcurrency` | `16` | `32` |
155
+ | `task.maxEffort` | `xhigh` | `max` |
156
+ | `task.maxRuntimeMs` | `3600000` | `0` |
157
+ | `task.agentIdleTtlMs` | `120000` | `420000` |
158
+ | `task.enableLsp` | `true` | `false` |
159
+ | `task.eager` | `always` | `default` |
160
+ | `task.showResolvedModelBadge` | `true` | `false` |
161
+ | `find.enabled` | `true` | `auto` |
162
+ | `providers.webSearchTimeoutSeconds` | `30` | `60` |
163
+ | `browser.idleCloseSec` | `600` | `1800` |
164
+ | `steeringMode` | `all` | `one-at-a-time` |
165
+ | `doubleEscapeAction` | `tree` | `rewind` |
166
+ | `features.unexpectedStopDetection` | `smart` | `mechanical` |
167
+ | `compaction.idleEnabled` | `true` | `false` |
168
+ | `compaction.handoffSaveToDisk` | `true` | `false` |
169
+ | `commands.enableOpencodeProject` | `false` | `true` |
170
+ | `statusLine.compactThinkingLevel` | `false` | `true` |
171
+ | `github.enabled` | `true` | `false` |
172
+
173
+ Sync cannot tell the old kit value from the same value that you set again.
174
+ It prunes both on every sync. To keep an old kit value, set it in a project
175
+ configuration or in a `PI_CONFIG_FILES` file, which sync does not write.
176
+
177
+ The `github` tool is off by default. Its `pr_push` operation runs git
178
+ directly, so the `bash.patterns` guards do not see it. The `issue://` and
179
+ `pr://` read schemes do not need the tool. omp reads them through its GitHub
180
+ cache and `gh` (`omp://tools/read.md`, `omp://tools/github.md`), so they still
181
+ work with `github.enabled: false`. The plan-lifecycle work reads issues with
182
+ `gh` in bash, so the change does not affect it.
183
+
184
+ ### Overrides that stay
185
+
186
+ - `branchSummary.enabled: true`.
187
+ - `dev.autoqa: false` with `dev.autoqaConsent: denied`.
188
+ - `codexResets.autoRedeem5h: "no"` and `codexResets.autoRedeemWeekly: "no"`.
189
+ - `startup.quiet: true`.
190
+ - `display.showTokenUsage: true`.
191
+ - The model roles, `cycleOrder`, `retry.fallbackChains`, `modelTags`, the
192
+ reviewer overrides in `task.agentModelOverrides` and
193
+ `task.agentServiceTierOverrides`, and the `bash.patterns` guards.
@@ -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
@@ -656,13 +657,15 @@ keeps a block that the user edited.
656
657
  not onto level names: `lo` selects the lowest level, `med` the lower middle,
657
658
  and `hi` the highest (`resolveTaskEffortLevel` in omp's
658
659
  `packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
659
- `task.maxEffort`. On the `low, medium, high, xhigh, max` ladder, `hi` gave
660
- `xhigh` under the `xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh
661
- despite the `:high` role suffix. On 2026-11-05, a fresh `omp -p` run on omp
662
- 18.16.0 with the field off had no `effort` field, and its `task` child
663
- recorded `resolvedModel: anthropic/claude-opus-5-5:high`.
664
- - `task.maxEffort` is `xhigh`. With `task.enableEffort` off, the cap applies
665
- only to a per-call `model` with a `:level` suffix.
660
+ `task.maxEffort`. Up to 0.23.0 the kit set that cap to `xhigh`. On the
661
+ `low, medium, high, xhigh, max` ladder, `hi` then gave `xhigh`, so many
662
+ `task` spawns ran Opus 5.5 xhigh despite the `:high` role suffix. On
663
+ 2026-11-05, a fresh `omp -p` run on omp 18.16.0 with the field off had no
664
+ `effort` field, and its `task` child recorded
665
+ `resolvedModel: anthropic/claude-opus-5-5:high`.
666
+ - Since 0.24.0 the kit sets no `task.maxEffort`, so the cap is omp's default
667
+ `max`. With `task.enableEffort` off, the cap applies only to a per-call
668
+ `model` with a `:level` suffix.
666
669
  - In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
667
670
  four reviewer agents resolve `@reviewer` and run GPT-6.1 Terra `high` on the
668
671
  live tier of the main session. A `docks-kit omp` free session replaces
@@ -702,9 +705,10 @@ web-search provider order therefore applies, and that order includes the paid
702
705
  deployed retry chain, such as a `plan`, `slow`, or `designer` chain, therefore
703
706
  stays in the merged config. A retry of the free model does not reach such a
704
707
  chain, because omp uses the empty chain keyed by the free model first.
705
- The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
706
- a model that publishes no thinking ladder, where both keys are omitted and the
707
- deployed or omp default values apply.
708
+ The overlay also sets `defaultThinkingLevel` and `task.maxEffort` to the
709
+ session level. For a model that publishes no thinking ladder, the overlay
710
+ omits both keys. A value in the deployed config then applies, or else the omp
711
+ default, which is `max` for `task.maxEffort`.
708
712
 
709
713
  The launcher renders a run overlay to
710
714
  `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
@@ -800,7 +804,7 @@ bare selectors with no `:level` suffix, because an invented level makes omp
800
804
  fail when the session starts.
801
805
 
802
806
  The choice persists per machine in `~/.docks-kit/kit.db` (table
803
- `omp_session`), next to the harness selection. It survives across sessions. It is never
807
+ `omp_session`). It survives across sessions. It is never
804
808
  committed. `--model <selector>` records one selector and derives the level
805
809
  from the catalog row. `--pick` opens an interactive wizard.
806
810
 
@@ -915,4 +919,7 @@ on normal processing, use `docks-kit omp --fast` and a new session, not
915
919
  - Update the capture date in the same commit as any number.
916
920
  - Verify Astra ladder changes in `SoT/.omp/models.yml` through the model
917
921
  switcher and in-session thinking control.
918
- - Verify `task.maxEffort` changes with a fresh `omp -p` spawn per bundled agent.
922
+ - The kit leaves `task.maxEffort` and `task.enableEffort` at omp's defaults,
923
+ `max` and `false`. After an omp update, check both in
924
+ `omp config list --json`. Verify a kit change to either key with a fresh
925
+ `omp -p` spawn per bundled agent.
@@ -1,15 +1,14 @@
1
1
  # docks-kit overview
2
2
 
3
- docks-kit is a portable configuration kit for AI coding agents. Per-tool
4
- Single Source of Truth (SoT) directories are deployed to each tool's
5
- user-config location — clone once, sync everywhere, get a consistent
3
+ docks-kit is a portable configuration kit for AI coding agents. Its Single
4
+ Source of Truth (SoT) directory `SoT/.omp/` deploys to the user-config location
5
+ of Oh My Pi (`omp`). Clone once, sync everywhere, and get a consistent
6
6
  AI-assisted dev environment on every machine.
7
7
 
8
8
  ## Pieces
9
9
 
10
10
  | Piece | Role |
11
11
  |-------|------|
12
- | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
13
12
  | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
14
13
  | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
15
14
  | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
@@ -23,9 +22,7 @@ AI-assisted dev environment on every machine.
23
22
  - **Quiet on no-ops**: by default a re-run prints only real changes, warnings
24
23
  (with a platform-correct install command when a tool is missing), and the
25
24
  summary; `--verbose` / `-v` also prints the no-op confirmations.
26
- - **Additive by default**: user-only keys/plugins/skills survive a plain sync.
27
- Removing kit-managed universal skills that left the SoT is explicit:
28
- `--prune`.
25
+ - **Additive by default**: user-only keys and plugins survive a plain sync.
29
26
  - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
30
27
  EngineNative owns mutation. No-Bun recovery is a platform release binary.
31
28
  - **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
@@ -34,5 +31,5 @@ AI-assisted dev environment on every machine.
34
31
  ## Where to go next
35
32
 
36
33
  - `docks-kit docs sync-layers` — what a sync actually touches
37
- - `docks-kit docs flags` — full flag reference + old→new renames
34
+ - `docks-kit docs flags` — full flag reference
38
35
  - `docks-kit toolchain` — doctor view of this machine's external tools
@@ -1,13 +1,12 @@
1
1
  # Sync layers
2
2
 
3
- `docks-kit sync [agents] [omp]` — targets are positional words; no target
4
- means this machine's harness selection in `~/.docks-kit/kit.db`. The default
5
- is `agents omp`, and `docks-kit harnesses` changes it.
6
-
7
- ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
8
-
9
- `npx skills add` per missing manifest slug, `~/.claude/skills` symlink
10
- healing, and the kit-owned record that `--prune` removes against.
3
+ `docks-kit sync` deploys the omp SoT. It takes no positional target. Sync
4
+ writes no `.agents` or `.claude` folder of its own; omp's folders follow
5
+ `PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
6
+ that points into one of those folders makes omp's files go there. omp uses
7
+ `XDG_DATA_HOME` only on Linux and macOS, only while `PI_CODING_AGENT_DIR`
8
+ does not move the agent folder, and only after the omp folder under it
9
+ exists. Sync also writes the kit plugin to `~/.docks-kit/omp-plugin`.
11
10
 
12
11
  ## omp (→ resolved agent dir, intercom root)
13
12
 
@@ -26,83 +25,53 @@ retired in 0.22.8), config.yml keys whose deployed value still equals the value
26
25
  ship, `providers.webSearchOrder` at any value, and the retired
27
26
  `providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
28
27
  it still matches the shipped block.
29
- Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
30
- registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
31
- through `omp plugin`, and `pi-intercom` is installed at its
32
- `SoT/toolchain.json` pin. Inventory comes from `omp plugin list --json`, where a
33
- marketplace row counts as installed only when its `scope` is `user`, so a repeat
34
- run is a no-op and a project-only row still installs. When just the legacy
35
- config-root registry lists `docks`, omp copies it forward itself: the sync runs
36
- `marketplace update`, or the read-only `marketplace list` under
37
- `--skip-plugin-refresh`, which keeps installs but fetches nothing. After a
38
- plugin operation, the sync reads the inventory again and prints one line that
39
- names each plugin with its version change, for example
40
- `omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
41
-
42
- omp deletes the previous plugin folder on `omp plugin upgrade`. A running omp
43
- session then loses the plugin agents of that folder. A test on omp 18.16.0
44
- showed that `/reload-plugins` brings the agents back, and that `skill://`
45
- resolves to the new folder (#139). The omp marketplace docs still ask for a
46
- restart for hooks, extension modules, and non-MCP tools. For each marketplace
47
- upgrade that changed the version, the sync prints a warning, for example
48
- `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).`
49
- The next step then says
50
- `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.`
51
- A version-changing upgrade does not set the restart trigger. Each other plugin
52
- operation sets it: an install, a reinstall at the same version, an npm install,
53
- or a link. A changed kit plugin file or omp config file also sets it. The
54
- restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
55
- then prints next to the upgrade rule.
56
-
57
- The sync also writes one event file for each such upgrade into the upgrade log
58
- `~/.cache/docks-kit/omp-plugin-upgrades/` (folder 0700, files 0600). The file
59
- name is `<finishedAt ms>-<random>.json`, and the file holds
60
- `{"version":1,"id":"<id>","before":"<v>","after":"<v>","finishedAt":"<ISO time>"}`.
61
- `finishedAt` is the time just after the upgrade command returned. Each sync
62
- writes only new files, through a temporary name and a rename, so concurrent
63
- syncs keep all events. Then it removes the oldest files beyond the newest 100.
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`.
64
32
 
65
- If the inventory read after the operations fails, the sync cannot see the new
66
- versions. It then warns
67
- `omp plugin versions could not be read after the upgrade — each upgraded plugin counts as changed`.
68
- Each upgrade of a present marketplace plugin then counts as a change. It gets
69
- the warning and an event with the after version `unknown`, for example
70
- `docks@docks 0.21.1 -> unknown`.
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:
71
39
 
72
- A failed write or prune of the upgrade log does not fail the sync, because it
73
- is not a harness CLI operation. A failed write warns
74
- `omp plugin upgrade log not written: <error> — running omp sessions get no reminder for these upgrades; give each of them the advice above`.
75
- The summary line, the upgrade warnings, and the next steps stay. A failed prune
76
- keeps the new events and warns
77
- `omp plugin upgrade log not pruned: <error> — it can keep more than 100 event files`.
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.
78
57
 
79
- The kit plugin extension `pluginUpgrades.ts` reads the upgrade log. In each
80
- tool result of a main omp session, it takes the events that finished after
81
- its omp process started. It adds one reminder for the events that the session
82
- did not get before. The reminder names each plugin with its version change. It
83
- says that the plugin agents of the session may fail. It tells the agent to ask
84
- the user to run `/reload-plugins`. It then tells the agent to read each plugin
85
- skill again through `skill://` before it runs a skill script. It asks for a
86
- restart instead when an upgraded plugin ships hooks, extension modules, or
87
- non-MCP tools. A folder or file that the extension cannot read gives no
88
- reminder for that tool result. The next tool result reads it again.
89
- These limits apply:
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.
90
61
 
91
- - omp imports extension modules only at startup. An omp process that started
92
- before a sync deployed `pluginUpgrades.ts` did not load it. Its sessions get
93
- no reminder, also for the upgrades of that sync.
94
- - An upgrade that `docks-kit sync` did not run gives no reminder, for example
95
- `omp plugin upgrade` by hand.
96
- - The warning, the next step, and the reminder assume that the session loaded
97
- the user-scope install. omp keeps an old cache folder that a known project
98
- registry still uses. So a session on a project-scope install keeps its
99
- folder. For this reason, the reminder says "may".
100
- - An omp process that started during the upgrade can get a reminder that it
101
- does not need. A reload or a restart is harmless.
102
- - The log keeps the newest 100 events. A session that stays idle through more
103
- than 100 later upgrades loses the oldest ones.
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.
104
70
 
105
- 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`.
106
75
 
107
76
  Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
108
77
  plus directory probes, so a dry run still runs no omp subcommand. The agent
@@ -118,7 +87,10 @@ into `<agent directory>/intercom`. Otherwise it goes into
118
87
  `$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
119
88
  `~/.pi/agent/intercom`.
120
89
 
121
- ## Prune flag
90
+ ## Additive by default
122
91
 
123
- - `--prune` — the universal skills that `~/.agents/.kit-owned-skills` names
124
- and SoT no longer lists are removed.
92
+ Sync has no removal flag. A key, plugin, or file that only the user added
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.
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Field | Meaning |
6
6
  |-------|---------|
7
- | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool: `npx` for `skills-cli`, `omp install` for `pi-intercom`; the optional `via` field names that tool in the doctor table, and the default is `npx`) |
7
+ | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool, such as `omp install` for `pi-intercom`; the required `via` field names that tool in the doctor table) |
8
8
  | `policy` | Installation policy; `present` installs when missing and never upgrades |
9
9
  | `floor` | Minimum acceptable version shown in the doctor table |
10
10
  | `verified` | Last kit-tested version and the exact pin for kit-driven installs |
@@ -31,15 +31,14 @@ an installer. An already-present Bun skips that download on every host.
31
31
 
32
32
  ## Supply-chain stance
33
33
 
34
- Every kit-driven package install from npm, npx, GitHub releases, or
34
+ 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
- the `npx skills@<verified>` invocations on agents sync and the release workflow
38
- (actions pinned to commit SHAs, exact bun/npm versions). 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.
37
+ the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
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
package/cli/src/argv.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  import { GlobalFlag } from "effect/cli";
2
2
  import { docsCommand } from "./commands/docs";
3
- import { harnessesCommand } from "./commands/harnesses";
4
- import { skillsCommand } from "./commands/skills";
5
3
  import { syncCommand } from "./commands/sync";
6
4
  import { toolchainCommand } from "./commands/toolchain";
7
5
  import { updateCommand } from "./commands/update";
@@ -28,10 +26,8 @@ export type ArgvOutcome =
28
26
  */
29
27
  export const COMMANDS = [
30
28
  syncCommand,
31
- harnessesCommand,
32
29
  updateCommand,
33
30
  toolchainCommand,
34
- skillsCommand,
35
31
  docsCommand,
36
32
  ompCommand,
37
33
  scratchCommand,
@@ -1,10 +1,9 @@
1
1
  /**
2
- * Per-command validation for the Effect CLI layer: legacy-flag hints,
3
- * unknown-command/flag detection, and boolean-value and duplicate rejection.
2
+ * Per-command validation for the Effect CLI layer: unknown-command/flag
3
+ * detection, and boolean-value and duplicate rejection.
4
4
  * Operates on scanned flags so the grammar machinery stays in argvSurface.ts.
5
5
  */
6
6
 
7
- import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
8
7
  import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
9
8
 
10
9
  /**
@@ -25,12 +24,6 @@ export const validateScannedArgv = (
25
24
  return `unknown command '${subcommand}'`;
26
25
  }
27
26
 
28
- if (subcommand === "sync") {
29
- for (const flag of flags) {
30
- if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
31
- }
32
- }
33
-
34
27
  // Effect 4 expands clustered shorts, but the kit declares no clusterable alias
35
28
  // pair, so refusing a cluster as one unknown flag is the conservative direction.
36
29
  for (const flag of flags) {
@@ -14,10 +14,10 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
14
14
  const TOPICS: Record<string, { summary: string; body: string }> = {
15
15
  overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
16
16
  "sync-layers": {
17
- summary: "The two sync targets (agents, omp) and additive-by-default semantics",
17
+ summary: "How sync deploys the omp SoT, and its additive-by-default semantics",
18
18
  body: syncLayers,
19
19
  },
20
- flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
20
+ flags: { summary: "Full flag reference", body: flags },
21
21
  toolchain: {
22
22
  summary: "Verified-version floors, the doctor table, and the upstream outdated report",
23
23
  body: toolchain,
@@ -10,7 +10,7 @@ import {
10
10
  readOmpSessionModel,
11
11
  writeOmpSessionModel,
12
12
  type OmpSessionModel,
13
- } from "../engine-native/harnesses";
13
+ } from "../engine-native/ompSession";
14
14
  import {
15
15
  buildOmpArgs,
16
16
  ladderCeiling,
@@ -4,7 +4,7 @@ import { Argument, Command } from "effect/cli";
4
4
  import { Console, Effect } from "effect";
5
5
 
6
6
  import { bail } from "../engine";
7
- import { engineHome } from "../engine-native/harnesses";
7
+ import { engineHome } from "../engine-native/ompSession";
8
8
  import {
9
9
  allowedRemovalRoots,
10
10
  createScratchDir,
@@ -1,8 +1,8 @@
1
- import { Argument, Command, Flag } from "effect/cli";
1
+ import { Command, Flag } from "effect/cli";
2
2
  import { Effect } from "effect";
3
3
  import { existsSync } from "node:fs";
4
4
  import { join } from "node:path";
5
- import { bail, engine } from "../engine";
5
+ import { engine } from "../engine";
6
6
  import { spawnHost } from "../engine-native/exec";
7
7
  import type { Logger } from "../engine-native/logger";
8
8
  import { kitHome } from "../kitHome";
@@ -35,21 +35,10 @@ export const updateNudge = (logger: Logger): void => {
35
35
  }
36
36
  };
37
37
 
38
- const VALID_TARGETS = ["agents", "omp"];
39
-
40
- const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
41
- Argument.withDescription("Sync targets: agents, omp (default: selected harnesses)"),
42
- Argument.variadic(),
43
- );
44
-
45
38
  const dryRun = Flag.Boolean("dry-run").pipe(
46
39
  Flag.withDescription("Preview without applying"),
47
40
  Flag.withDefault(false),
48
41
  );
49
- const prune = Flag.Boolean("prune").pipe(
50
- Flag.withDescription("Remove kit-managed universal skills not in SoT/.agents/skills.txt"),
51
- Flag.withDefault(false),
52
- );
53
42
  const skipPluginRefresh = Flag.Boolean("skip-plugin-refresh").pipe(
54
43
  Flag.withDescription(
55
44
  "Install missing plugins but skip refresh-only updates for existing plugins",
@@ -65,24 +54,14 @@ const verbose = Flag.Boolean("verbose").pipe(
65
54
  export const syncCommand = Command.make(
66
55
  "sync",
67
56
  {
68
- targets,
69
57
  dryRun,
70
- prune,
71
58
  skipPluginRefresh,
72
59
  verbose,
73
60
  },
74
61
  (config) =>
75
62
  Effect.gen(function* () {
76
- const bad = config.targets.filter((t) => !VALID_TARGETS.includes(t));
77
- if (bad.length > 0) {
78
- return yield* bail(
79
- `Unknown sync target(s): ${bad.join(", ")} (valid: ${VALID_TARGETS.join(", ")})`,
80
- );
81
- }
82
-
83
- const args: Array<string> = ["sync", ...config.targets];
63
+ const args: Array<string> = ["sync"];
84
64
  if (config.dryRun) args.push("--dry-run");
85
- if (config.prune) args.push("--prune");
86
65
  if (config.skipPluginRefresh) args.push("--skip-plugin-refresh");
87
66
  if (config.verbose) args.push("--verbose");
88
67
 
@@ -4,7 +4,7 @@ import { Command, Flag } from "effect/cli";
4
4
  import { Console, Effect, Option } from "effect";
5
5
 
6
6
  import { bail } from "../engine";
7
- import { engineHome } from "../engine-native/harnesses";
7
+ import { engineHome } from "../engine-native/ompSession";
8
8
  import { acquireKitLock, releaseKitLock } from "../engine-native/kitLock";
9
9
  import { scratchRoot, tidyApplyLockPath } from "../engine-native/scratch";
10
10
  import {
@@ -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
  );