opensocrates 1.1.0 → 1.1.3

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ParkerHwang/OpenSocrates/main/docs/assets/opensocrates-banner.jpg" alt="OpenSocrates" width="820">
+</p>
+
 # OpenSocrates
 
 **English** | [한국어](README.ko.md)
@@ -13,19 +17,31 @@ uses a fresh host-native selector to choose relevant systems, and adds their
 complete theory and examples to the active task. Straightforward factual and
 mechanical work can pass through unchanged.
 
-Version `1.1.0` includes 48 reasoning systems and release packages for Claude
-and Codex on Apple-silicon macOS (`darwin-arm64`). It uses your existing host
-login and does not require an API key or an OpenSocrates backend.
+Version `1.1.3` includes 48 reasoning systems, one user-facing Claude entry, a
+Claude grounding gate that verifies selected procedures were read, coordinated
+Claude/Codex lifecycle management, and opt-in automatic updates on
+Apple-silicon macOS (`darwin-arm64`). It uses your existing host login and does
+not require an API key or an OpenSocrates backend.
+
+The native plugin archives intentionally ship only `bin/launch.sh`. That
+launcher accepts `darwin-arm64` only; macOS Intel, Linux, and Windows launchers
+and runtimes are not shipped or supported in this release.
+
+> **Latest release: [OpenSocrates 1.1.3](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.3).**
+> It adds authenticated live-host validation, installer and cleanup hardening,
+> strict package support boundaries, and an uploadable Claude Chat skills ZIP.
+> Upgrade both managed hosts together with
+> `npx --yes opensocrates@1.1.3 update --host all`.
 
 ## Host support
 
-| Host surface | Automatic selection | Reasoning skills | Validation status |
+| Host surface | Automatic selection | User-facing entry | Validation status |
 | --- | --- | --- | --- |
-| Codex CLI and Desktop | Yes | Yes | Release-validated on `darwin-arm64` |
-| Claude Code CLI | Yes, through `UserPromptSubmit` | Yes | Locally validated on `darwin-arm64` |
-| Claude Code desktop app | Implemented, where Claude Code plugins run | Yes | Implemented; no live probe receipt |
-| Claude Cowork | Implemented, when the local plugin runtime is available | Yes | Experimental; no live probe receipt |
-| Claude web and Desktop Chat | No hooks | Yes, through plugin skills | Skills-only; upload path unvalidated |
+| Codex CLI and Desktop | Yes | OpenSocrates plugin | Release-validated on `darwin-arm64` |
+| Claude Code CLI | Yes, through `UserPromptSubmit` | `/opensocrates` | Locally validated on `darwin-arm64` |
+| Claude Code desktop app | Yes, where Claude Code plugins run | `/opensocrates` | [Authenticated hook lifecycle locally validated](docs/claude-desktop-live-probe.md) |
+| Claude Cowork | No automatic hooks in the tested install | `/opensocrates` standalone skill | [Skill locally validated; native plugin blocked by archive limits](docs/claude-cowork-live-probe.md) |
+| Claude web and Desktop Chat | No hooks | `/opensocrates` | [Live upload and invocation validated](docs/claude-chat-upload-probe.md) |
 
 The status column uses four distinct levels. Do not read them as
 interchangeable:
@@ -43,11 +59,13 @@ skills, but automatic per-prompt selection is available only on Claude Code
 and Cowork surfaces that execute the plugin runtime. OpenSocrates fails open
 if a hook or selector is unavailable.
 
-Cowork carries one further unverified assumption. OpenSocrates registers its
-marketplace with `claude plugin marketplace add --scope user`, which writes
-Claude Code user settings. Anthropic documents that plugin hooks run in Cowork,
-but does not document that a marketplace registered through the Claude Code CLI
-is visible to Cowork. Until a receipt exists, treat Cowork as experimental.
+Cowork does not import the Claude Code CLI user-marketplace registration as a
+native Cowork plugin in the current live UI. A separately uploaded
+`/opensocrates` skill is locally validated, but the published v1.1.2 Claude
+plugin archive exceeds Cowork's documented compressed limit and observed
+uncompressed limit. The repository also lacks a Cowork marketplace manifest.
+Until a Cowork-native plugin can be installed and its hooks re-probed, treat
+Cowork as a standalone-skill-only surface.
 
 ## Install
 
@@ -61,47 +79,90 @@ small, dependency-free installer. It downloads the matching package from
 GitHub Releases and verifies the release checksum and every file checksum
 before registering an owner-marked managed marketplace.
 
-### Claude Code and Cowork
+### Install every ready host
 
 ```bash
-npx --yes opensocrates@1.1.0 install --host claude
+npx --yes opensocrates@1.1.3 install --host all
 ```
 
-Lifecycle commands:
+The all-host path detects supported, authenticated host CLIs, completes every
+preflight before changing either host, verifies and stages both packages, and
+then activates one release transactionally. If one activation fails, every
+host already changed in that transaction is restored to its previous managed
+registration.
+
+Use the same host value for the complete lifecycle:
 
 ```bash
-npx --yes opensocrates@1.1.0 status --host claude
-npx --yes opensocrates@1.1.0 update --host claude
-npx --yes opensocrates@1.1.0 remove --host claude
+npx --yes opensocrates@1.1.3 status --host all
+npx --yes opensocrates@1.1.3 update --host all
+npx --yes opensocrates@1.1.3 remove --host all
 ```
 
-### Codex
+A private `~/.opensocrates/desired-state.json` manifest records the selected
+channel, installed hosts, and desired active version. `status --host all`
+reports the desired and available versions, last check, last successful
+automatic update, and per-host drift.
+
+### Install one host explicitly
 
 Codex remains the default host for backward compatibility:
 
 ```bash
-npx --yes opensocrates@1.1.0 install
-# Equivalent: npx --yes opensocrates@1.1.0 install --host codex
+npx --yes opensocrates@1.1.3 install
+# Equivalent: npx --yes opensocrates@1.1.3 install --host codex
+npx --yes opensocrates@1.1.3 install --host claude
 ```
 
-Lifecycle commands:
+Existing `--host codex` and `--host claude` lifecycle commands remain
+supported. A host-specific update can intentionally create drift; a later
+`update --host all` or successful automatic reconciliation brings every host
+recorded in desired state back to one version.
+
+For Claude, status distinguishes an enabled installation from an
+installed-but-disabled plugin. A disabled desired installation is reported as
+drift. Running `install` or `update` intentionally installs the verified
+package enabled again; if activation fails, rollback restores the previous
+enabled or disabled state. The installer accepts only the observed direct JSON
+arrays and explicit `marketplaces`/`plugins` wrappers from Claude's list
+commands. The privacy-safe 2.1.226 fixture is under
+`installer/fixtures/claude-cli/`.
+
+### Opt-in automatic updates
 
 ```bash
-npx --yes opensocrates@1.1.0 status --host codex
-npx --yes opensocrates@1.1.0 update --host codex
-npx --yes opensocrates@1.1.0 remove --host codex
+npx --yes opensocrates@1.1.3 auto-update enable --host all
+npx --yes opensocrates@1.1.3 auto-update status
+npx --yes opensocrates@1.1.3 auto-update disable
 ```
 
-To use both hosts, run both install commands. Their managed marketplaces live
-under their respective Claude and Codex configuration homes.
+Automatic updates are disabled until explicitly enabled. The macOS LaunchAgent
+starts a bounded hourly poll; desired state applies the configured interval
+(24 hours by default) with jitter and a single-instance lock. The job invokes
+the selected npm channel, verifies release and package checksums, stages every
+managed host, and reconciles them as one transaction. Major-version upgrades
+are blocked by default; use `--allow-major` only when that policy is intended.
+
+Passing one host to `auto-update enable` narrows only the automatic-update
+scope. It never removes another installed host from desired state;
+`status --host all` continues to track every installation, and a later
+`update --host all` still reconciles the complete installed set.
+
+The updater keeps a private receipt with version, time, per-host result, and an
+error category only. It never records prompts, transcripts, credentials, or
+workspace paths. `auto-update disable` unloads and removes the LaunchAgent;
+`remove --host all` does the same before removing the managed hosts.
 
 ### Claude web and Desktop Chat skills
 
 These surfaces support plugin skills but not hooks. Download
-`opensocrates-1.1.0-claude-chat-skills.zip` from the release and upload it from
-Claude's plugin customization UI. The 48 method skills and three shared skills
-remain available in a small, runtime-free package, while automatic selection
-is absent because Chat does not execute plugin hooks. See Anthropic's
+`opensocrates-1.1.3-claude-chat-skills.zip` from the release and upload it from
+Claude's **Customize → Skills → Upload skill** UI. The ZIP contains one
+top-level `opensocrates/` folder with `SKILL.md` directly inside, as required by
+the skill uploader. The package exposes exactly one
+`/opensocrates` skill; its 48 method procedures, rigor, evidence, and trace
+controls are internal supporting references. Automatic selection is absent
+because Chat does not execute plugin hooks. See Anthropic's
 [plugin surface guide](https://support.claude.com/en/articles/13837440-use-plugins-in-claude).
 
 ### Install from a tagged GitHub source
@@ -109,21 +170,22 @@ is absent because Chat does not execute plugin hooks. See Anthropic's
 The same host option works without the npm registry:
 
 ```bash
-npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host claude
-npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host codex
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.3 install --host all
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.3 install --host claude
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.3 install --host codex
 ```
 
 ### Manual release verification
 
 Download `opensocrates.mjs`, the host package, and its `.sha256` file from the
-[v1.1.0 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.0).
+[v1.1.3 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.3).
 For Claude, for example:
 
 ```bash
-shasum -a 256 -c opensocrates-1.1.0-claude-plugin.zip.sha256
+shasum -a 256 -c opensocrates-1.1.3-claude-plugin.zip.sha256
 node opensocrates.mjs install --host claude \
-  --asset opensocrates-1.1.0-claude-plugin.zip \
-  --checksum opensocrates-1.1.0-claude-plugin.zip.sha256
+  --asset opensocrates-1.1.3-claude-plugin.zip \
+  --checksum opensocrates-1.1.3-claude-plugin.zip.sha256
 ```
 
 Replace `claude` with `codex` for the Codex package.
@@ -138,9 +200,13 @@ what is installed, remove it explicitly:
 ```bash
 claude plugin uninstall opensocrates@OpenSocrates --scope user
 claude plugin marketplace remove OpenSocrates --scope user
-npx --yes opensocrates@1.1.0 install --host claude
+npx --yes opensocrates@1.1.3 install --host claude
 ```
 
+Updating a managed v1.1.0 Claude installation replaces the complete package
+tree. Its old 48 top-level method skills, `rigor`, `trace`, and duplicate
+commands are therefore removed rather than left visible as stale entries.
+
 ## Use
 
 Use Claude or Codex normally. Before a submitted prompt, OpenSocrates may
@@ -151,14 +217,43 @@ reasoning process. When it intervenes, it:
 1. starts a fresh, non-persistent selector in the current host;
 2. chooses from the authored 48-system catalog;
 3. writes the complete selected content to an owner-only temporary Markdown
-   file; and
-4. adds a small hidden context message telling the active task to read it.
+   file;
+4. adds a bounded hidden context message with each method ID, content revision,
+   and, when they fit, its exact `Do not use when` and `Stop conditions`; and
+5. requires the active task to read the complete file before applying the
+   method and to end a grounded response with an exact audit line such as
+   `OpenSocrates grounding: triangulation@1`.
+
+On Claude hook surfaces, a Read-only `PostToolUse` hook records an authenticated
+receipt only when the exact current-turn file is read from its first line
+through a terminal marker. At `Stop`, a missing receipt or audit line requests
+one bounded repair pass; `stop_hook_active` prevents a continuation loop. A
+partial, truncated, failed, or wrong-file read is not accepted. Claude Chat
+does not run these hooks, so its grounding contract remains skills-only.
+
+The receipt records that a successful `Read` callback for that exact file
+returned content reaching the terminal marker. It is not a proof that every byte
+was delivered, and the gate fails open. See [SECURITY.md](SECURITY.md) for the
+boundary this does and does not defend.
 
 There is no fixed selection-count limit. The selector has a 30-second internal
 deadline, does not retry, and fails open. A timeout, host error, invalid output,
 non-intervention decision, unsafe context, or unavailable hook produces no
 injection and does not block the user's task.
 
+On Claude, explicitly invoke the same controller when desired:
+
+```text
+/opensocrates <request>
+/opensocrates auto <request>
+/opensocrates trace
+/opensocrates status
+```
+
+Only `/opensocrates` appears in Claude's skill and command UI. The controller
+selects and loads internal method references; users do not need to browse the
+48-system implementation catalog.
+
 The Claude selector uses one `claude --safe-mode -p` process with no session
 persistence. Safe mode disables user, project, and plugin customizations:
 `CLAUDE.md`, skills, plugins, hooks, MCP servers, custom commands, and agents.
@@ -195,9 +290,20 @@ telemetry, store an API key, or execute the user's requested task.
 Temporary instruction files contain authored OpenSocrates content only. Raw
 prompts, transcripts, workspace files, tool data, credentials, and selector
 reasoning are not written to OpenSocrates records, logs, metrics, diagnostics,
-or instruction files. Turn files are removed on `Stop`, remaining session
-files on `SessionEnd`, and crash leftovers older than 24 hours on
-`SessionStart`.
+or instruction files. The complete Read response is inspected only in memory
+for its terminal marker and is not retained. The owner-only grounding receipt
+stores only an artifact digest, content revision, selected method IDs, and
+keyed authentication/tool-use tags—never a prompt, tool output, workspace path,
+or artifact path. Turn files and receipts are removed on `Stop`. If `Stop` never
+arrives, the next `UserPromptSubmit` in the same session removes every prior
+`prompt_id` tree before selecting for the new turn while preserving the new
+active tree. `SessionEnd` removes anything still left in the session, and the
+next `SessionStart` removes crash leftovers older than 24 hours.
+
+When enabled, the updater stores only desired lifecycle state and the concise
+receipt described above, under owner-only permissions. It does not inspect or
+terminate running Claude or Codex sessions; a running task keeps its loaded
+plugin, and a new task naturally loads the reconciled version.
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting and the measured
 support boundary.
@@ -208,6 +314,26 @@ The source repository intentionally excludes native binaries and intermediate
 build output. Install [uv](https://docs.astral.sh/uv/), Python 3.12, and Node.js
 20 or later, then run:
 
+Before merging a release candidate, follow the
+[clean Apple-silicon Mac acceptance procedure](docs/clean-machine-acceptance.md)
+to exercise the real authenticated Claude Code and Codex homes and return a
+privacy-safe evidence bundle.
+
+The selector's authenticated Claude subprocess contract has a separate
+[opt-in check](docs/real-claude-selector.md). The authenticated v1.1.2 receipt
+passes the real subprocess isolation and structured-output contract; the live
+call is never rerun by the ordinary offline suite.
+
+Repeated `--max-turns 1` structured-output behavior has a separate
+[aggregate reliability matrix](docs/claude-structured-output-reliability.md).
+The authenticated Claude Code 2.1.226 `host-default` row passed 20/20 attempts;
+no unobserved named model is claimed supported.
+
+Packaged Claude PostToolUse receipt and Stop cleanup latency has a reproducible
+[Apple-silicon timing receipt](docs/claude-hook-timing.md). The observed v1.1.2
+p95 results retain more than half of the 3-second hook budget, so the timeout is
+unchanged.
+
 ```bash
 make bootstrap
 make format-check

package/SECURITY.md

@@ -41,6 +41,11 @@ OpenSocrates 1.x:
 - does not require or store an Anthropic or OpenAI API key;
 - does not host an OpenSocrates backend or add telemetry;
 - verifies downloadable packages with SHA-256 release and package manifests;
+- keeps cross-host activation transactional and restores prior managed
+  registrations when a coordinated activation fails;
+- leaves scheduled updates disabled until explicitly enabled and stores only
+  owner-readable desired state, a single-instance lock, and content-free update
+  receipts;
 - fails open when the selector cannot safely complete.
 
 The Claude selector runs a bounded, non-persistent `claude --safe-mode -p`
@@ -74,7 +79,45 @@ authored catalog content assembled by OpenSocrates is ever injected. Operators
 who cannot accept managed-hook visibility of the selector prompt should not
 enable OpenSocrates selection on those machines.
 
+On Claude surfaces that deliver the packaged hooks, the grounding gate observes
+only successful `Read` callbacks for the current turn's exact instruction file.
+It transiently checks that the response reached an authored terminal marker and
+does not retain the response. The owner-only authenticated receipt stores only
+the artifact digest, content revision, selected method IDs, and keyed
+authentication/tool-use tags; prompts, transcripts, raw tool output,
+credentials, workspace paths, and artifact paths are excluded. `Stop` removes
+the receipt with the turn artifact. If `Stop` is absent, the next
+`UserPromptSubmit` in that session removes prior prompt trees without touching
+the new active tree. `SessionEnd` remains the session backstop, and the
+24-hour `SessionStart` sweep covers crash leftovers when neither event arrives.
+
+The gate's scope is deliberate and worth stating plainly. It establishes that a
+successful `Read` callback naming the exact current-turn artifact returned
+content reaching the authored terminal marker. It does not cryptographically
+prove that every artifact byte was returned: a synthetic payload carrying only
+the marker would satisfy the marker test. That is not reachable by the model,
+which does not author `tool_response`, and the marker is the artifact's last
+line, so a truncated read loses it. Anything able to forge that callback already
+controls the hook's standard input and is outside the boundary this gate
+defends. The gate raises the cost of an ungrounded answer; it is not a proof of
+delivery, and it fails open by design.
+
+The optional macOS LaunchAgent invokes the selected published npm channel and
+then uses the same verified installer path as a manual update. It does not read
+or terminate active Claude or Codex sessions. Its receipt contains only the
+checked version, timestamp, per-host result, and an error category; prompts,
+transcripts, workspace paths, credentials, and raw error output are excluded.
+Automatic major-version upgrades are disabled unless the user explicitly
+changes that policy.
+
+Installer rollback mutates only its owner-marked managed marketplace root. If
+the failed root cannot be removed and the previous backup therefore cannot be
+renamed into place, the installer preserves that backup and prints quoted,
+executable recovery commands naming only those two managed paths.
+
 Signing, notarization, clean-machine installation, platforms other than
 `darwin-arm64`, Claude Chat automatic hooks, and live delivery on every host
-surface are not claimed as validated. See the release limitations file for the
-complete measured boundary.
+surface are not claimed as validated. Native plugin archives ship only
+`bin/launch.sh`; it rejects macOS Intel, Linux, Windows, and every other target,
+and no PowerShell launcher is included. See the release limitations file for
+the complete measured boundary.

package/VERSION

@@ -1 +1 @@
-1.1.0
+1.1.3