docks-kit 0.24.0 → 0.26.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 (49) hide show
  1. package/AGENTS.md +21 -136
  2. package/README.md +54 -9
  3. package/cli/dist/docks-kit.js +24688 -0
  4. package/cli/docs/command-guards.md +1 -1
  5. package/cli/docs/install.md +30 -9
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +5 -4
  8. package/cli/docs/sync-layers.md +46 -75
  9. package/cli/docs/toolchain.md +4 -5
  10. package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
  11. package/cli/src/agentDocs/bridgeCheck.ts +226 -0
  12. package/cli/src/agentDocs/commands.ts +63 -0
  13. package/cli/src/agentDocs/prTemplate.ts +211 -0
  14. package/cli/src/agentDocs/services.ts +202 -0
  15. package/cli/src/agentDocs/shared.ts +730 -0
  16. package/cli/src/agentDocs/verifySkill.ts +136 -0
  17. package/cli/src/argv.ts +25 -1
  18. package/cli/src/commands/agentDocs.ts +29 -0
  19. package/cli/src/commands/plan.ts +29 -0
  20. package/cli/src/commands/skill.ts +29 -0
  21. package/cli/src/commands/update.ts +90 -31
  22. package/cli/src/engine-native/DESIGN.md +5 -6
  23. package/cli/src/engine-native/engineCtx.ts +0 -3
  24. package/cli/src/engine-native/failures.ts +2 -2
  25. package/cli/src/engine-native/ompChild.ts +1 -1
  26. package/cli/src/engine-native/ompKitPlugin.ts +7 -16
  27. package/cli/src/engine-native/ompPlugins.ts +205 -221
  28. package/cli/src/engine-native/ompSync.ts +5 -14
  29. package/cli/src/generated/sotPayload.ts +308 -12
  30. package/cli/src/main.ts +12 -3
  31. package/cli/src/plan/bytes.ts +110 -0
  32. package/cli/src/plan/checkout.ts +341 -0
  33. package/cli/src/plan/commands.ts +1192 -0
  34. package/cli/src/plan/github.ts +816 -0
  35. package/cli/src/plan/records.ts +623 -0
  36. package/cli/src/plan/repository.ts +53 -0
  37. package/cli/src/plan/reviews.ts +292 -0
  38. package/cli/src/plan/services.ts +256 -0
  39. package/cli/src/plan/types.ts +164 -0
  40. package/cli/src/skills/commands.ts +142 -0
  41. package/cli/src/skills/config.json +30 -0
  42. package/cli/src/skills/files.ts +74 -0
  43. package/cli/src/skills/frontmatter.ts +148 -0
  44. package/cli/src/skills/guard.ts +366 -0
  45. package/cli/src/skills/kitGate.ts +406 -0
  46. package/cli/src/skills/rubric.ts +143 -0
  47. package/cli/tsconfig.json +1 -0
  48. package/package.json +7 -4
  49. package/cli/src/engine-native/ompMarketplace.ts +0 -140
@@ -10,7 +10,7 @@ The policy keeps only deny rules. Where omp's critical-command check acts,
10
10
  the form is denied. omp also denies a `$` or a backtick after `git push`,
11
11
  because the agent can always write the ref literally.
12
12
 
13
- By owner decision (0.22.8, #126), the kit ships no omp
13
+ By owner decision (0.22.8, DocksDocks/public#126), the kit ships no omp
14
14
  prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
15
15
  allow. Under omp's default `tools.approvalMode: yolo`, omp runs every
16
16
  command that no deny matches without a question, in the main session and in
@@ -6,8 +6,8 @@ Hosts outside this matrix fail before a launcher can fall back to Bun source.
6
6
  ## 1. Repo checkout (development / current users)
7
7
 
8
8
  ```
9
- git clone https://github.com/DocksDocks/public.git ~/projects/public
10
- cd ~/projects/public
9
+ git clone https://github.com/DocksDocks/docks-kit.git ~/projects/docks-kit
10
+ cd ~/projects/docks-kit
11
11
  ./docks-kit sync
12
12
  ```
13
13
 
@@ -17,6 +17,23 @@ version matches `package.json`. It then falls back to Bun-from-source and
17
17
  auto-installs Bun plus `node_modules` when needed. Each launcher reports and
18
18
  bypasses an ignored stale build.
19
19
 
20
+ ### Move a checkout of DocksDocks/public
21
+
22
+ The kit moved from DocksDocks/public to DocksDocks/docks-kit. To move a
23
+ checkout of DocksDocks/public, run these commands from the checkout's root:
24
+
25
+ ```
26
+ git remote set-url origin https://github.com/DocksDocks/docks-kit.git
27
+ ./docks-kit update # Linux and macOS
28
+ .\docks-kit.ps1 update # Windows
29
+ ./docks-kit sync # Linux and macOS
30
+ .\docks-kit.ps1 sync # Windows
31
+ ```
32
+
33
+ The update pulls from DocksDocks/docks-kit. The sync then deploys the skills
34
+ with their new report target: a launcher that runs a fresh compiled binary
35
+ skips the sync that the update chains. A global npm install needs nothing.
36
+
20
37
  ## 2. Global via Bun
21
38
 
22
39
  ```
@@ -26,8 +43,11 @@ docks-kit sync
26
43
  bunx docks-kit toolchain check
27
44
  ```
28
45
 
29
- The npm package bundles the CLI and its generated in-memory payload — releases
30
- are versioned config snapshots without publishing the authoring `SoT/` tree.
46
+ The npm package runs one minified JavaScript bundle of the CLI and its generated
47
+ in-memory payload (`cli/dist/docks-kit.js`) — releases are versioned config
48
+ snapshots without publishing the authoring `SoT/` tree. Identifiers stay
49
+ unminified, so a stack trace keeps its names; the source map is a GitHub
50
+ release asset (`docks-kit.js.map`), matched by the bundle's `//# debugId=` line.
31
51
  Kit-home resolution remains available for checkout/package update behavior and
32
52
  display paths, but sync reads do not depend on it.
33
53
 
@@ -49,7 +69,7 @@ a copy that lags behind the pinned release.
49
69
  ## 3. curl installer (POSIX)
50
70
 
51
71
  ```
52
- tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/public/main/install.sh -o "$tmp" && bash "$tmp"; rc=$?; rm -f "$tmp"; (exit "$rc")
72
+ tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.sh -o "$tmp" && bash "$tmp"; rc=$?; rm -f "$tmp"; (exit "$rc")
53
73
  ```
54
74
 
55
75
  Download-then-run, never `curl | bash` — stream truncation has bitten this
@@ -61,7 +81,7 @@ installer below.
61
81
  ## 4. PowerShell installer (Windows)
62
82
 
63
83
  ```powershell
64
- Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/public/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
84
+ Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
65
85
  powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\docks-kit-install.ps1"
66
86
  Remove-Item "$env:TEMP\docks-kit-install.ps1"
67
87
  ```
@@ -108,9 +128,10 @@ worktree and an upstream; `git pull --ff-only`, then re-runs
108
128
  `bun install --frozen-lockfile` when the pull changed `bun.lock` or
109
129
  `package.json`); a kit home under `node_modules` is a global package
110
130
  (`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.
131
+ plain flag-less `docks-kit sync`. It also refreshes plugins, even when the kit
132
+ is already current: it moves `pi-intercom` to its pinned version. Pass
133
+ `--no-sync`, then run `docks-kit sync --skip-plugin-refresh` to keep a present
134
+ `pi-intercom` at its installed version.
114
135
  A compiled binary inside a checkout updates the checkout; on the next invocation
115
136
  the launcher bypasses that now-stale binary and uses updated source until rebuilt.
116
137
  Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
@@ -124,7 +124,7 @@ keys carries a kit value that differs from the default omp already applies.
124
124
 
125
125
  ## omp 19.0.0 tools and returned overrides
126
126
 
127
- The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
127
+ The owner made these decisions on 2026-11-19 (DocksDocks/public#184). They apply from 0.24.0.
128
128
 
129
129
  ### Tools that the kit turns on
130
130
 
@@ -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
@@ -522,7 +523,7 @@ At `high`, Sol produces about 19% more tokens per second than Terra. At
522
523
  `xhigh`, the gain is about 24%. Sol also has the lower TTFT and end-to-end
523
524
  time at both levels.
524
525
 
525
- The `reviewer` role stays on GPT-6.1 Terra `high`. The #130 benchmark chose
526
+ The `reviewer` role stays on GPT-6.1 Terra `high`. The DocksDocks/public#130 benchmark chose
526
527
  Terra by escaped defects, not by speed. omp 18.22.2 lists no GPT-6.2 Terra. A
527
528
  move of the reviewer to GPT-6.2 Sol needs a new benchmark.
528
529
 
@@ -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