opensocrates 1.0.0 → 1.1.2

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)
@@ -7,121 +11,252 @@
 [![Release](https://img.shields.io/github/v/release/ParkerHwang/OpenSocrates)](https://github.com/ParkerHwang/OpenSocrates/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-OpenSocrates is a local reasoning framework for AI-agent hosts. It detects
-requests that benefit from deliberate reasoning, selects relevant reasoning
-systems in a separate Codex context, and adds their authored theory and
-examples to the active task. Straightforward factual and mechanical work can
-pass through unchanged.
-
-Version `1.0.0` includes 48 reasoning systems and supports Codex Desktop and
-Codex CLI on Apple-silicon macOS (`darwin-arm64`). Other platforms, binary
-signing, notarization, and clean-machine installation are not yet claimed as
-validated.
+OpenSocrates is a local integration and authored reasoning framework for
+Claude and Codex. It detects requests that benefit from deliberate reasoning,
+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.2` 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.
+
+> **Latest release: [OpenSocrates 1.1.2](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2).**
+> It adds authenticated Claude grounding receipts, one bounded repair pass,
+> and artifact-instance-bound replay protection. Upgrade both managed hosts
+> together with `npx --yes opensocrates@1.1.2 update --host all`.
+
+## Host support
+
+| Host surface | Automatic selection | User-facing entry | Validation status |
+| --- | --- | --- | --- |
+| 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 | Implemented, where Claude Code plugins run | `/opensocrates` | Implemented; no live probe receipt |
+| Claude Cowork | Implemented, when the local plugin runtime is available | `/opensocrates` | Experimental; no live probe receipt |
+| Claude web and Desktop Chat | No hooks | `/opensocrates` | Skills-only; upload path unvalidated |
+
+The status column uses four distinct levels. Do not read them as
+interchangeable:
+
+- **Implemented** — the integration exists in code and ships in the package.
+- **Locally validated** — exercised end to end on a maintainer machine, but
+  not on every build.
+- **Release-validated** — exercised by the release gate on every build.
+- **Experimental / no live probe receipt** — implemented, but no captured
+  receipt shows the host actually delivering the hook. `os capabilities show`
+  reports these capabilities as `unknown`, not as available.
+
+Claude Chat surfaces do not run plugin hooks. They can use the generated
+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.
 
 ## Install
 
-Before installing, sign in to Codex with OAuth and make sure the `codex`
-command is available.
+Before installing, sign in to the host and make sure its command is available:
+
+- Claude: Claude Code `2.1.205` or later and the `claude` command;
+- Codex: an OAuth-authenticated `codex` command.
 
-### Option 1: npx from npm
+Node.js 20 or later is required. The published `opensocrates` npm package is a
+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.
 
-Requires Node.js 20 or later. The npm package is a small, dependency-free
-installer; it downloads and verifies the matching package from GitHub
-Releases.
+### Install every ready host
 
 ```bash
-npx --yes opensocrates@1.0.0 install
+npx --yes opensocrates@1.1.2 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.0.0 status
-npx --yes opensocrates@1.0.0 update
-npx --yes opensocrates@1.0.0 remove
+npx --yes opensocrates@1.1.2 status --host all
+npx --yes opensocrates@1.1.2 update --host all
+npx --yes opensocrates@1.1.2 remove --host all
 ```
 
-### Option 2: npx from GitHub
+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
 
-Requires Node.js 20 or later. This command installs directly from the tagged
-GitHub repository and remains available without the npm registry.
+Codex remains the default host for backward compatibility:
 
 ```bash
-npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 install
+npx --yes opensocrates@1.1.2 install
+# Equivalent: npx --yes opensocrates@1.1.2 install --host codex
+npx --yes opensocrates@1.1.2 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.
+
+### Opt-in automatic updates
 
 ```bash
-npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 status
-npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 update
-npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 remove
+npx --yes opensocrates@1.1.2 auto-update enable --host all
+npx --yes opensocrates@1.1.2 auto-update status
+npx --yes opensocrates@1.1.2 auto-update disable
 ```
 
-The installer downloads the matching GitHub Release asset, verifies both the
-release checksum and every checksum inside the package, and then registers a
-private managed marketplace under the current Codex home.
+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.2-claude-chat-skills.zip` from the release and upload it from
+Claude's plugin customization UI. 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).
 
-### Option 3: download from GitHub Releases
+### Install from a tagged GitHub source
 
-Download `opensocrates.mjs` from the
-[v1.0.0 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0),
-then run:
+The same host option works without the npm registry:
 
 ```bash
-node opensocrates.mjs install
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host all
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host claude
+npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host codex
 ```
 
-For a fully manual download and checksum check:
+### Manual release verification
+
+Download `opensocrates.mjs`, the host package, and its `.sha256` file from the
+[v1.1.2 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2).
+For Claude, for example:
 
 ```bash
-curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip
-curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip.sha256
-shasum -a 256 -c opensocrates-1.0.0-codex-plugin.zip.sha256
-node opensocrates.mjs install \
-  --asset opensocrates-1.0.0-codex-plugin.zip \
-  --checksum opensocrates-1.0.0-codex-plugin.zip.sha256
+shasum -a 256 -c opensocrates-1.1.2-claude-plugin.zip.sha256
+node opensocrates.mjs install --host claude \
+  --asset opensocrates-1.1.2-claude-plugin.zip \
+  --checksum opensocrates-1.1.2-claude-plugin.zip.sha256
 ```
 
-### Option 4: build and install from source
+Replace `claude` with `codex` for the Codex package.
+
+### Migrating a pre-1.0 Claude plugin
 
-Requires [uv](https://docs.astral.sh/uv/) and Python 3.12.
+Some development builds used a case-sensitive marketplace named
+`OpenSocrates`. The new marketplace is `opensocrates`. The installer detects
+the old registration and refuses to remove it automatically. After reviewing
+what is installed, remove it explicitly:
 
 ```bash
-git clone https://github.com/ParkerHwang/OpenSocrates.git
-cd OpenSocrates
-uv python install 3.12
-uv sync --locked --all-groups
-make release-check
-uv run --locked --no-sync python tools/codex_plugin.py install
+claude plugin uninstall opensocrates@OpenSocrates --scope user
+claude plugin marketplace remove OpenSocrates --scope user
+npx --yes opensocrates@1.1.2 install --host claude
 ```
 
-`make release-check` builds the native runtime and installable package locally.
-Generated files are written to ignored `build/` and `dist/` directories.
+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 Codex normally. Before each submitted prompt, OpenSocrates may intervene
-when the request needs judgment, interpretation, diagnosis, explanation,
-planning, evidence reconciliation, or another structured reasoning process.
-When it intervenes, it:
+Use Claude or Codex normally. Before a submitted prompt, OpenSocrates may
+intervene when the request needs judgment, interpretation, diagnosis,
+explanation, planning, evidence reconciliation, or another structured
+reasoning process. When it intervenes, it:
 
-1. uses a fresh, ephemeral selector thread;
+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 one hidden context message telling the active task to read that file.
-
-There is no fixed selection-count limit. The hook message stays small while
-the full selected theory and examples remain uncompressed in the referenced
-file.
-
-The selector has a 30-second internal deadline, does not retry, and fails open.
-A timeout, SDK error, invalid output, non-intervention decision, unsafe
-context, or unavailable hook produces no injection and does not block the
-user's task.
+   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
+```
 
-To prevent the selector from requesting bounded transcript context:
+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.
+OpenSocrates additionally passes `--tools ""`, `--disallowedTools "mcp__*"`,
+and `--strict-mcp-config` so that no built-in or MCP tool remains available. It
+receives only the current prompt and the authored selection catalog.
+
+Managed policy settings are part of the host trust boundary and are **not**
+disabled by safe mode. Anthropic's
+[CLI reference](https://code.claude.com/docs/en/cli-reference) states that under
+`--safe-mode` "managed settings policy still applies, including
+policy-configured hooks". On a machine where an administrator configures a
+managed `UserPromptSubmit` hook, that hook runs inside the selector process,
+receives the current prompt on standard input, and can return
+`additionalContext` that enters selection. Managed plugins, managed skills,
+managed `CLAUDE.md`, and policy-configured MCP servers do not load. If your
+organization configures managed hooks, treat the selector prompt as visible to
+them and disable OpenSocrates selection if that is unacceptable.
+
+The Codex selector can additionally use bounded transcript context unless
+disabled:
 
 ```bash
 export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
@@ -129,24 +264,40 @@ export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
 
 ## Privacy and security
 
-OpenSocrates runs locally through the Codex app-server and the user's existing
-Codex OAuth session. It does not require an API key, host a backend, execute
-the user's requested task, or add telemetry.
+OpenSocrates runs its integration locally and uses the existing Claude or
+Codex login. Host model requests are still processed by the selected host
+service under that service's terms. OpenSocrates does not host a backend, add
+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, OAuth credentials, and
-selector reasoning are not written to records, logs, metrics, diagnostics, or
-temporary instruction files. Turn files are removed on `Stop`, remaining
+prompts, transcripts, workspace files, tool data, credentials, and selector
+reasoning are not written to OpenSocrates records, logs, metrics, diagnostics,
+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`, remaining
 session files on `SessionEnd`, and crash leftovers older than 24 hours on
 `SessionStart`.
 
-See [SECURITY.md](SECURITY.md) for vulnerability reporting and the current
+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.
 
 ## Develop
 
 The source repository intentionally excludes native binaries and intermediate
-build output. Install the locked development environment and run:
+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.
 
 ```bash
 make bootstrap
@@ -162,12 +313,11 @@ npm pack --dry-run
 make release-check
 ```
 
-Repository layout:
-
 | Path | Purpose |
 | --- | --- |
-| `src/opensocrates/` | Python 3.12 runtime and selector source |
+| `src/opensocrates/` | Shared Python 3.12 runtime and host-native selectors |
 | `content/` | Policies, localized messages, methods, theory, and examples |
+| `plugin-src/claude/` | Claude plugin templates |
 | `plugin-src/codex/` | Codex plugin templates |
 | `schemas/source/` | Canonical schema definitions |
 | `schemas/v1/` | Generated, versioned public schemas |
@@ -177,8 +327,8 @@ Repository layout:
 | `build/`, `dist/` | Generated locally and published as release assets |
 
 Generated schemas and compiled content must be changed through their canonical
-sources and generators. Release binaries belong in GitHub Releases, not in the
-Git history.
+sources and generators. Release binaries belong in GitHub Releases, not in Git
+history.
 
 ## Contributing
 
@@ -191,3 +341,6 @@ requests. The project follows the [Code of Conduct](CODE_OF_CONDUCT.md).
 OpenSocrates is available under the [MIT License](LICENSE). You may use,
 modify, distribute, sublicense, and sell copies, provided the copyright and
 license notice are preserved.
+
+OpenSocrates is an independent open-source project and is not affiliated with
+or endorsed by Anthropic or OpenAI.

package/SECURITY.md

@@ -34,14 +34,80 @@ severity, and the availability of a safe fix.
 
 ## Security boundary
 
-OpenSocrates 1.0:
+OpenSocrates 1.x:
 
-- runs locally through Codex and uses the user's existing OAuth session;
-- does not require or store an OpenAI API key;
+- runs its integration locally through Claude or Codex and uses the user's
+  existing host login;
+- 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`
+process. Safe mode disables user, project, and plugin customizations, and
+OpenSocrates additionally passes `--tools ""`, `--disallowedTools "mcp__*"`, and
+`--strict-mcp-config` so no built-in or MCP tool remains. It receives the current
+prompt and authored selection catalog only. The process uses the user's Claude
+login, so model requests remain subject to Anthropic's service and data-handling
+terms. The Codex selector uses the pinned Codex SDK and existing OAuth session in
+its own isolated worker.
+
+The selector environment is default-deny. `CLAUDE_CONFIG_DIR` is one of the
+small set of allowed path variables because the child needs it to locate the
+user's existing Claude login when a non-default config directory is in use.
+OpenSocrates does not copy, inspect, or log credentials from that directory.
+
+Managed policy settings are part of the host trust boundary and are not disabled.
+Anthropic's [CLI reference](https://code.claude.com/docs/en/cli-reference) states
+that under `--safe-mode` "managed settings policy still applies, including
+policy-configured hooks". Consequences on an organization-managed machine:
+
+- a managed `UserPromptSubmit` hook executes inside the selector process,
+  receives the current prompt on standard input, and can return
+  `additionalContext` that enters selection;
+- managed plugins, managed skills, managed `CLAUDE.md`, and policy-configured
+  MCP servers do not load.
+
+OpenSocrates does not detect or override managed policy. Selection remains
+bounded regardless: the model's returned instruction text is discarded, and only
+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, and the 24-hour sweep covers crash leftovers.
+
+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.
+
 Signing, notarization, clean-machine installation, platforms other than
-`darwin-arm64`, and actual host hook delivery are not claimed as validated.
-See the release limitations file for the complete measured boundary.
+`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.

package/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.2