opensocrates 1.2.0 → 1.2.1

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 (6) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/README.ko.md +169 -63
  3. package/README.md +178 -72
  4. package/VERSION +1 -1
  5. package/installer/opensocrates.mjs +2336 -97
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -12,12 +12,14 @@
12
12
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
13
13
 
14
14
  OpenSocrates is a local integration and authored reasoning framework for
15
- Claude, Codex, Grok Build, and OpenCode. It detects requests that benefit from deliberate reasoning,
16
- uses a fresh host-native selector to choose relevant systems, and adds their
17
- complete theory and examples to the active task. Straightforward factual and
18
- mechanical work can pass through unchanged.
19
-
20
- Version `1.2.0` adds first-class OpenCode support to the 48 reasoning systems,
15
+ Google Antigravity, Claude, Codex, Cursor, Grok Build, and OpenCode. It preserves
16
+ each host's delivery model: Claude/Codex hidden trusted context leads with
17
+ teacher questions, Antigravity/Cursor/Grok expose question-led complete
18
+ procedures through skills, and OpenCode injects one such procedure in the same
19
+ turn with the native skill as fallback. Straightforward factual and mechanical
20
+ work can pass through unchanged.
21
+
22
+ Version `1.2.0` added first-class OpenCode support to the 48 reasoning systems,
21
23
  including stable same-turn activation, a native skill fallback, coordinated
22
24
  multi-host lifecycle management, and opt-in automatic updates on
23
25
  Apple-silicon macOS (`darwin-arm64`). It uses your existing host login and does
@@ -27,11 +29,12 @@ The native plugin archives intentionally ship only `bin/launch.sh`. That
27
29
  launcher accepts `darwin-arm64` only; macOS Intel, Linux, and Windows launchers
28
30
  and runtimes are not shipped or supported in this release.
29
31
 
30
- > **Latest release: OpenSocrates 1.2.0.** It adds experimental Antigravity and
31
- > Cursor skill packages, live-validated native Grok Build support, and OpenCode
32
- > 1.18.18+ with a stable `chat.message` bridge and native Agent Skill fallback.
33
- > Upgrade managed hosts together with
34
- > `npx --yes opensocrates@1.2.0 update --host all`.
32
+ > **Current release: OpenSocrates 1.2.1.** It adds a committed, mutation-tested
33
+ > v1.2 adjudication snapshot and a bilingual three-question teacher overlay
34
+ > across all six host packages. It also adds safe complete-uninstall and Codex
35
+ > trust-reset flows, tighter Claude provenance boundaries, same-machine
36
+ > reinstall acceptance, and source-complete Codex SessionStart timing evidence.
37
+ > The separate Claude Chat v1.2.1 live-upload receipt remains pending.
35
38
 
36
39
  ## Host support
37
40
 
@@ -43,10 +46,10 @@ and runtimes are not shipped or supported in this release.
43
46
  | Grok Build TUI | Native plugin is shared with headless; activation receipt pending | `/opensocrates` | [TUI hook execution verified, native skill marker test pending; shipped package has no hooks](docs/grok-support.md) |
44
47
  | OpenCode TUI and `opencode run` | Yes; stable same-turn local bridge | Native `opensocrates` skill | [OpenCode 1.18.18 TUI, `opencode run`, and DeepSeek V4 Flash live smoke validated](docs/opencode-support.md) |
45
48
  | Codex CLI and Desktop | Yes, after one-time in-app hook approval | OpenSocrates plugin | Package and launcher release-validated on `darwin-arm64`; no live Codex hook-delivery receipt |
46
- | Claude Code CLI | Yes, through `UserPromptSubmit` | `/opensocrates` | Locally validated on `darwin-arm64` |
47
- | Claude Code desktop app | Yes, where Claude Code plugins run | `/opensocrates` | [Authenticated hook lifecycle locally validated](docs/claude-desktop-live-probe.md) |
48
- | Claude Cowork | Yes, in the tested local plugin upload | `/opensocrates` | [Native hook lifecycle locally validated; direct release upload, no marketplace sync](docs/claude-cowork-live-probe.md) |
49
- | Claude web and Desktop Chat | No hooks | `/opensocrates` | [Live upload and invocation validated](docs/claude-chat-upload-probe.md) |
49
+ | Claude Code CLI | Yes, through `UserPromptSubmit` | Plugin: `/opensocrates:opensocrates` | Locally validated on `darwin-arm64` |
50
+ | Claude Code desktop app, Local mode | Yes, where Claude Code plugins run | Plugin: `/opensocrates:opensocrates` | [Authenticated hook lifecycle locally validated](docs/claude-desktop-live-probe.md) |
51
+ | Claude Cowork with the local plugin | Yes, in the tested local plugin upload | Plugin: `/opensocrates:opensocrates` | [Native hook lifecycle locally validated; direct release upload, no marketplace sync](docs/claude-cowork-live-probe.md) |
52
+ | Claude web and Desktop Chat | No OpenSocrates hooks | Standalone skill: `/opensocrates` | [Historical v1.1.2 upload validated; exact v1.2.1 release and live upload pending](docs/claude-chat-upload-probe.md) |
50
53
 
51
54
  The status column uses four distinct levels. Do not read them as
52
55
  interchangeable:
@@ -60,10 +63,23 @@ interchangeable:
60
63
  receipt shows the host actually delivering the hook. `os capabilities show`
61
64
  reports these capabilities as `unknown`, not as available.
62
65
 
63
- Claude Chat surfaces do not run plugin hooks. They can use the generated
64
- skills, but automatic per-prompt selection is available only on Claude Code
65
- and Cowork surfaces that execute the plugin runtime. OpenSocrates fails open
66
- if a hook or selector is unavailable.
66
+ The Claude plugin's canonical explicit command is
67
+ `/opensocrates:opensocrates`, following Anthropic's
68
+ [plugin namespace contract](https://code.claude.com/docs/en/plugins). A current
69
+ Claude version can also offer `/opensocrates` as a bare alias when no other
70
+ command owns that name, but the alias is not the canonical plugin contract and
71
+ does not prove which skill source answered. The separately uploaded Chat ZIP
72
+ is a standalone skill and canonically uses `/opensocrates`. Chat surfaces do
73
+ not run the packaged OpenSocrates hooks; automatic per-prompt selection is
74
+ available only on Claude Code and Cowork surfaces that execute the plugin
75
+ runtime. OpenSocrates fails open if a hook or selector is unavailable.
76
+
77
+ Keep three Claude provenance states separate: the installer-managed local
78
+ plugin, a standalone ZIP manually uploaded to Chat, and any pre-existing
79
+ synced/custom skill. Local plugin status cannot prove or update either Cloud
80
+ state. The currently recorded local plugin version is 1.2.1, while the
81
+ pre-existing synced/custom observation is 1.1.2; neither is evidence that an
82
+ exact v1.2.1 standalone release ZIP was uploaded.
67
83
 
68
84
  The published v1.1.2 Claude plugin archive exceeded Cowork's documented
69
85
  compressed limit and observed uncompressed limit. A pre-release v1.1.3
@@ -94,7 +110,7 @@ before registering an owner-marked managed marketplace.
94
110
  ### Install every ready host
95
111
 
96
112
  ```bash
97
- npx --yes opensocrates@1.2.0 install --host all
113
+ npx --yes opensocrates@1.2.1 install --host all
98
114
  ```
99
115
 
100
116
  The all-host path detects supported, authenticated host CLIs, completes every
@@ -106,11 +122,74 @@ registration.
106
122
  Use the same host value for the complete lifecycle:
107
123
 
108
124
  ```bash
109
- npx --yes opensocrates@1.2.0 status --host all
110
- npx --yes opensocrates@1.2.0 update --host all
111
- npx --yes opensocrates@1.2.0 remove --host all
125
+ npx --yes opensocrates@1.2.1 status --host all
126
+ npx --yes opensocrates@1.2.1 update --host all
127
+ npx --yes opensocrates@1.2.1 remove --host all
128
+ ```
129
+
130
+ ### Remove a registration, purge owned payloads, or reset Codex trust
131
+
132
+ Ordinary `remove` keeps its backward-compatible, narrow contract: it removes
133
+ the selected exact host registration and installer-managed root and reconciles
134
+ the updater, but it may leave host-owned OpenSocrates plugin caches and the
135
+ installer desired-state file. Its output names every remaining known
136
+ OpenSocrates path and the purge command to run next; it does not describe that
137
+ result as a complete uninstall.
138
+
139
+ After closing active hosts, request the explicit owned-payload purge:
140
+
141
+ ```bash
142
+ npx --yes opensocrates@1.2.1 remove --host all --purge
143
+ # One host: npx --yes opensocrates@1.2.1 remove --host claude --purge
144
+ # Also reset only OpenSocrates Codex hook trust:
145
+ npx --yes opensocrates@1.2.1 remove --host all --purge --reset-trust
146
+ # Codex only: npx --yes opensocrates@1.2.1 remove --host codex --purge --reset-trust
112
147
  ```
113
148
 
149
+ Purge verifies canonical paths, the exact `opensocrates@opensocrates` package
150
+ identity, manifests, checksums, and installer ownership markers before deleting
151
+ anything. It covers the managed roots, exact Claude/Codex cache versions, empty
152
+ Claude OpenSocrates plugin-data directories, OpenCode's owned skill/bridge/
153
+ sidecar, the OpenSocrates LaunchAgent, known transaction residue, and—after the
154
+ lifecycle lock is released—the final known installer state files and an empty
155
+ state directory. It never recursively deletes broad host parents such as
156
+ `~/.claude/plugins`, `~/.codex/plugins`, or `~/.opensocrates`.
157
+
158
+ An active Claude cache with a live `.in_use/<pid>`, a missing host CLI that
159
+ prevents registration verification, a symlink, an invalid marker or manifest,
160
+ nonempty unverified plugin data, or a cleanup/permission failure makes the
161
+ result `pending` or failed and the command exits unsuccessfully. Close the
162
+ host or resolve the reported path and rerun the same purge command; a completed
163
+ purge is idempotent. Other plugins and user task, project, chat, plan, and
164
+ history data are preserved byte-for-byte.
165
+
166
+ The four removal surfaces remain separate:
167
+
168
+ - **Plugin registration:** ordinary remove and purge ask the selected host to
169
+ remove only the exact `opensocrates@opensocrates` registration.
170
+ - **Payload and installer state:** `--purge` verifies ownership before removing
171
+ the exact cache/data/managed-state paths described above.
172
+ - **Host security trust:** Codex hook approval is not payload. Purge preserves
173
+ it by default and reports that fact. Add `--reset-trust` explicitly with
174
+ `--host codex` or `--host all` to reset only the seven canonical
175
+ OpenSocrates hook approvals.
176
+ - **User history:** task, project, chat, plan, session, and history content is
177
+ never a removal target and remains byte-for-byte unchanged.
178
+
179
+ Codex CLI 0.145.0 has no supported narrow trust-removal command, so this opt-in
180
+ fallback targets only the exact `CODEX_HOME/config.toml`. It removes canonical
181
+ OpenSocrates sections for `pre_tool_use`, `post_tool_use`, `pre_compact`,
182
+ `session_start`, `session_end`, `user_prompt_submit`, and `stop`, without
183
+ hard-coding or printing their hashes. Other settings, plugins, comments, order,
184
+ whitespace, and LF/CRLF style are preserved. A symlink, noncanonical matching
185
+ section, unexpected key, invalid config, unsupported Codex validator, concurrent
186
+ change, or write/validation failure makes the purge partial. The original
187
+ config is retained or transactionally restored when rollback remains safe. If
188
+ a later external edit makes automatic rollback unsafe, that edit is not
189
+ overwritten and the owner-only recovery copy is preserved. No complete result
190
+ is claimed. Reinstallation is expected to present those seven hooks as new
191
+ approvals; that live approval flow still requires separate host evidence.
192
+
114
193
  A private `~/.opensocrates/desired-state.json` manifest records the selected
115
194
  channel, installed hosts, and desired active version. `status --host all`
116
195
  reports the desired and available versions, last check, last successful
@@ -121,13 +200,13 @@ automatic update, and per-host drift.
121
200
  Codex remains the default host for backward compatibility:
122
201
 
123
202
  ```bash
124
- npx --yes opensocrates@1.2.0 install
125
- # Equivalent: npx --yes opensocrates@1.2.0 install --host codex
126
- npx --yes opensocrates@1.2.0 install --host antigravity
127
- npx --yes opensocrates@1.2.0 install --host claude
128
- npx --yes opensocrates@1.2.0 install --host cursor
129
- npx --yes opensocrates@1.2.0 install --host grok
130
- npx --yes opensocrates@1.2.0 install --host opencode
203
+ npx --yes opensocrates@1.2.1 install
204
+ # Equivalent: npx --yes opensocrates@1.2.1 install --host codex
205
+ npx --yes opensocrates@1.2.1 install --host antigravity
206
+ npx --yes opensocrates@1.2.1 install --host claude
207
+ npx --yes opensocrates@1.2.1 install --host cursor
208
+ npx --yes opensocrates@1.2.1 install --host grok
209
+ npx --yes opensocrates@1.2.1 install --host opencode
131
210
  ```
132
211
 
133
212
  Antigravity installs a content-only plugin at
@@ -167,9 +246,9 @@ commands. The privacy-safe 2.1.226 fixture is under
167
246
  ### Opt-in automatic updates
168
247
 
169
248
  ```bash
170
- npx --yes opensocrates@1.2.0 auto-update enable --host all
171
- npx --yes opensocrates@1.2.0 auto-update status
172
- npx --yes opensocrates@1.2.0 auto-update disable
249
+ npx --yes opensocrates@1.2.1 auto-update enable --host all
250
+ npx --yes opensocrates@1.2.1 auto-update status
251
+ npx --yes opensocrates@1.2.1 auto-update disable
173
252
  ```
174
253
 
175
254
  Automatic updates are disabled until explicitly enabled. The macOS LaunchAgent
@@ -191,41 +270,55 @@ workspace paths. `auto-update disable` unloads and removes the LaunchAgent;
191
270
 
192
271
  ### Claude web and Desktop Chat skills
193
272
 
194
- These surfaces support plugin skills but not hooks. Download
195
- `opensocrates-1.2.0-claude-chat-skills.zip` from the release and upload it from
196
- Claude's **Customize → Skills → Upload skill** UI. The ZIP contains one
197
- top-level `opensocrates/` folder with `SKILL.md` directly inside, as required by
198
- the skill uploader. The package exposes exactly one
199
- `/opensocrates` skill; its 48 method procedures, rigor, evidence, and trace
200
- controls are internal supporting references. Automatic selection is absent
201
- because Chat does not execute plugin hooks. See Anthropic's
202
- [plugin surface guide](https://support.claude.com/en/articles/13837440-use-plugins-in-claude).
273
+ These surfaces can use a separately uploaded standalone skill but do not run
274
+ the local plugin hooks.
275
+
276
+ Exact v1.2.1 Chat release artifact: **unavailable; live upload pending.**
277
+
278
+ As of the 2026-08-15 audit, GitHub has no public `v1.2.1` tag or release, so
279
+ `opensocrates-1.2.1-claude-chat-skills.zip`, its checksum, and its release
280
+ commit cannot be verified or uploaded. Do not substitute a source-built
281
+ candidate or the Claude Code/Cowork plugin archive. The existing v1.1.2 live
282
+ receipt is historical evidence only, and the existing synced/custom skill was
283
+ left unchanged. See the [version-bound evidence and flip
284
+ conditions](docs/claude-chat-upload-probe.md).
285
+
286
+ When the exact release is published, verify its checksum before using Claude's
287
+ **Customize → Skills → Upload skill** UI. The ZIP must contain one top-level
288
+ `opensocrates/` folder with `SKILL.md` directly inside. It is not the Claude
289
+ Code/Cowork plugin archive. The standalone package exposes exactly one
290
+ canonical `/opensocrates` skill; its 48 method procedures, rigor, evidence, and
291
+ trace controls are internal supporting references. Automatic hook selection is
292
+ absent because Chat does not execute the packaged hooks. See Anthropic's
293
+ [custom skill guide](https://support.claude.com/en/articles/12512180-use-skills-in-claude).
203
294
 
204
295
  ### Install from a tagged GitHub source
205
296
 
206
- The same host option works without the npm registry:
297
+ The same host option works without the npm registry by using the published tag:
207
298
 
208
299
  ```bash
209
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host all
210
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host antigravity
211
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host claude
212
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host codex
213
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host cursor
214
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host grok
215
- npx --yes github:ParkerHwang/OpenSocrates#v1.2.0 install --host opencode
300
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host all
301
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host antigravity
302
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host claude
303
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host codex
304
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host cursor
305
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host grok
306
+ npx --yes github:ParkerHwang/OpenSocrates#v1.2.1 install --host opencode
216
307
  ```
217
308
 
218
309
  ### Manual release verification
219
310
 
220
- Download `opensocrates.mjs`, the host package, and its `.sha256` file from the
221
- [v1.2.0 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.2.0).
222
- For Claude, for example:
311
+ After publication, download `opensocrates.mjs`, the host package, and its
312
+ `.sha256` file from the
313
+ [v1.2.1 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.2.1).
314
+ That release was unavailable at the 2026-08-15 audit. The following is the
315
+ verification command to use only after all named assets exist; for Claude:
223
316
 
224
317
  ```bash
225
- shasum -a 256 -c opensocrates-1.2.0-claude-plugin.zip.sha256
318
+ shasum -a 256 -c opensocrates-1.2.1-claude-plugin.zip.sha256
226
319
  node opensocrates.mjs install --host claude \
227
- --asset opensocrates-1.2.0-claude-plugin.zip \
228
- --checksum opensocrates-1.2.0-claude-plugin.zip.sha256
320
+ --asset opensocrates-1.2.1-claude-plugin.zip \
321
+ --checksum opensocrates-1.2.1-claude-plugin.zip.sha256
229
322
  ```
230
323
 
231
324
  Replace `claude` with `antigravity`, `codex`, `cursor`, `grok`, or `opencode` for the matching package.
@@ -240,7 +333,7 @@ what is installed, remove it explicitly:
240
333
  ```bash
241
334
  claude plugin uninstall opensocrates@OpenSocrates --scope user
242
335
  claude plugin marketplace remove OpenSocrates --scope user
243
- npx --yes opensocrates@1.2.0 install --host claude
336
+ npx --yes opensocrates@1.2.1 install --host claude
244
337
  ```
245
338
 
246
339
  Updating a managed v1.1.0 Claude installation replaces the complete package
@@ -249,25 +342,34 @@ commands are therefore removed rather than left visible as stale entries.
249
342
 
250
343
  ## Use
251
344
 
252
- Use Claude, Codex, or OpenCode normally. Before a submitted prompt, OpenSocrates may
253
- intervene when the request needs judgment, interpretation, diagnosis,
254
- explanation, planning, evidence reconciliation, or another structured
255
- reasoning process. On Claude/Codex native-runtime surfaces it:
345
+ Use any supported host normally. OpenSocrates may participate when a request
346
+ needs judgment, interpretation, diagnosis, explanation, planning, evidence
347
+ reconciliation, or another structured reasoning process. On Claude/Codex
348
+ native-runtime surfaces it:
256
349
 
257
350
  1. starts a fresh, non-persistent selector in the current host;
258
351
  2. chooses from the authored 48-system catalog;
259
352
  3. writes the complete selected content to an owner-only Markdown file;
260
- 4. adds a bounded hidden context message with each method ID, content revision,
261
- and, when they fit, its exact `Do not use when` and `Stop conditions`; and
353
+ 4. adds a bounded hidden context message that leads with teacher questions to
354
+ settle, then each method ID, content revision, and, when they fit, its exact
355
+ `Do not use when` and `Stop conditions`; and
262
356
  5. requires the active task to read the complete file before applying the
263
357
  method and to end a grounded response with an exact audit line such as
264
358
  `OpenSocrates grounding: triangulation@1`.
265
359
 
266
360
  On OpenCode, the dependency-free stable hook instead selects locally and
267
- injects one complete authored procedure directly into the same message turn;
268
- it creates no artifact and makes no extra model call. See the
361
+ injects one complete authored procedure directly into the same message turn.
362
+ That compiled procedure starts with its three teacher questions, and the native
363
+ `/opensocrates` fallback reads the same procedure without a duplicate preamble;
364
+ the bridge creates no artifact and makes no extra model call. See the
269
365
  [OpenCode support boundary](docs/opencode-support.md).
270
366
 
367
+ Antigravity and Cursor use their explicit content skills; Grok Build uses native
368
+ skill selection or `/opensocrates`. In all three packages, a generated complete
369
+ procedure begins with teacher questions for the active agent to settle before
370
+ using the rest as a check. These content-only paths make no OpenSocrates hook
371
+ delivery claim.
372
+
271
373
  After installing for Codex, open one interactive Codex session and approve the
272
374
  OpenSocrates hooks before relying on automatic selection. Until that one-time
273
375
  approval, non-interactive surfaces such as `codex exec` may silently continue
@@ -303,15 +405,17 @@ injection and does not block the user's task.
303
405
  On Claude, explicitly invoke the same controller when desired:
304
406
 
305
407
  ```text
306
- /opensocrates <request>
307
- /opensocrates auto <request>
308
- /opensocrates trace
309
- /opensocrates status
408
+ /opensocrates:opensocrates <request>
409
+ /opensocrates:opensocrates auto <request>
410
+ /opensocrates:opensocrates trace
411
+ /opensocrates:opensocrates status
310
412
  ```
311
413
 
312
- Only `/opensocrates` appears in Claude's skill and command UI. The controller
313
- selects and loads internal method references; users do not need to browse the
314
- 48-system implementation catalog.
414
+ Those commands are for the Claude Code/Cowork plugin. The standalone Chat ZIP
415
+ uses `/opensocrates` instead. The plugin's registered command inventory names
416
+ `/opensocrates:opensocrates`; do not use a bare alias as source evidence. The
417
+ controller selects and loads internal method references, so users do not need
418
+ to browse the 48-system implementation catalog.
315
419
 
316
420
  The Claude selector uses one `claude --safe-mode -p` process with no session
317
421
  persistence. Safe mode disables user, project, and plugin customizations:
@@ -419,6 +523,7 @@ make lint
419
523
  make generated-check
420
524
  make content-check
421
525
  make docs-check
526
+ make governance-check
422
527
  make security-scan
423
528
  make smoke
424
529
  npm test
@@ -435,6 +540,7 @@ make release-check
435
540
  | `plugin-src/antigravity/` | Experimental Antigravity content-only plugin templates |
436
541
  | `plugin-src/cursor/` | Experimental Cursor Agent Plugin templates |
437
542
  | `plugin-src/grok/` | Native Grok Build content-only plugin templates |
543
+ | `plugin-src/opencode/` | OpenCode stable bridge and native skill templates |
438
544
  | `schemas/source/` | Canonical schema definitions |
439
545
  | `schemas/v1/` | Generated, versioned public schemas |
440
546
  | `installer/` | Dependency-free Node.js GitHub/npx installer |
package/VERSION CHANGED
@@ -1 +1 @@
1
- 1.2.0
1
+ 1.2.1