opensocrates 1.1.0 → 1.1.2

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 (7) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/README.ko.md +121 -38
  3. package/README.md +130 -39
  4. package/SECURITY.md +33 -0
  5. package/VERSION +1 -1
  6. package/installer/opensocrates.mjs +1347 -160
  7. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -3,6 +3,82 @@
3
3
  All notable changes to OpenSocrates are documented here. This project follows
4
4
  [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## [1.1.2] - 2026-08-11
7
+
8
+ ### Added
9
+
10
+ - A Claude `PostToolUse` grounding receipt that is created only after a
11
+ successful `Read` starts at the first line, reaches the instruction
12
+ artifact's terminal marker, and targets the current turn's exact file.
13
+ - One bounded `Stop` repair pass when Claude attempts to finish without a
14
+ verified read receipt or the exact public method/revision audit line.
15
+
16
+ ### Fixed
17
+
18
+ - Selected reasoning methods can no longer silently pass the Claude completion
19
+ gate when the model skips their required reference read and substitutes
20
+ prior knowledge. Each selected method is identified as
21
+ `method-id@content-revision`, and its authored `Do not use when` and
22
+ `Stop conditions` are inlined when they fit the trusted context budget
23
+ ([#32](https://github.com/ParkerHwang/OpenSocrates/issues/32)).
24
+ - A grounding read is recognized whatever shape the host uses to deliver the
25
+ `Read` response. The terminator search no longer depends on envelope key
26
+ names, which are not a stable host contract, so a host that wraps the body
27
+ differently no longer looks like an incomplete read and no longer costs a
28
+ compliant turn a repair pass. The search is bounded by an explicit depth limit
29
+ and the existing collection limits.
30
+
31
+ ### Security and privacy
32
+
33
+ - Grounding receipts are owner-only and authenticated. They contain only the
34
+ instruction artifact digest, content revision, selected method IDs, and
35
+ keyed tags; they never contain prompts, transcripts, tool output, credentials,
36
+ or workspace and artifact paths, and they are removed with the turn artifact.
37
+ - The complete `Read` response is inspected transiently for the terminal marker
38
+ and is neither retained nor projected into OpenSocrates records.
39
+ - The gate's scope is documented rather than implied. A receipt establishes that
40
+ a successful `Read` callback for the exact current-turn artifact returned
41
+ content reaching the terminal marker; it does not cryptographically prove that
42
+ every artifact byte was returned. A synthetic marker-only payload would
43
+ satisfy the marker test, which the model cannot produce because it does not
44
+ author `tool_response`.
45
+
46
+ ## [1.1.1] - 2026-08-10
47
+
48
+ ### Added
49
+
50
+ - One-command `--host all` support for install, status, update, remove, and
51
+ verification, backed by one desired-state manifest for the selected channel,
52
+ installed hosts, and active version.
53
+ - Cross-host preflight, package verification, staging, activation, and reverse
54
+ rollback so a partial Claude/Codex activation cannot leave a newly selected
55
+ version on only one host.
56
+ - Opt-in macOS LaunchAgent updates through `auto-update enable`, `status`,
57
+ `disable`, and the internal scheduled reconciliation command. Checks use a
58
+ bounded interval with jitter, a single-instance lock, compatible-version
59
+ policy, concise local receipts, and an update-target set kept separate from
60
+ the complete installed-host set.
61
+
62
+ ### Changed
63
+
64
+ - Claude now exposes one `/opensocrates` skill. The 48 method procedures,
65
+ rigor, evidence audit, trace, and status behavior are internal supporting
66
+ references or subcommands instead of separate top-level skills and commands.
67
+ - Updating a managed v1.1.0 Claude installation replaces the old multi-skill
68
+ package tree, removing stale top-level method and helper entries.
69
+ - `status --host all` reports the desired and available version, last check,
70
+ last successful update, and per-host drift.
71
+
72
+ ### Security and privacy
73
+
74
+ - Automatic updates remain disabled until explicitly enabled, verify both the
75
+ outer release checksum and complete package manifest before activation, and
76
+ preserve the previous registrations on preflight, verification, staging, or
77
+ activation failure.
78
+ - Desired state, locks, and receipts use owner-only permissions. Receipts keep
79
+ only version, time, per-host result, and error category; no prompts,
80
+ transcripts, credentials, or workspace paths are stored.
81
+
6
82
  ## [1.1.0] - 2026-08-06
7
83
 
8
84
  ### Added
@@ -90,3 +166,5 @@ All notable changes to OpenSocrates are documented here. This project follows
90
166
 
91
167
  [1.0.0]: https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0
92
168
  [1.1.0]: https://github.com/ParkerHwang/OpenSocrates/compare/v1.0.0...v1.1.0
169
+ [1.1.1]: https://github.com/ParkerHwang/OpenSocrates/compare/v1.1.0...v1.1.1
170
+ [1.1.2]: https://github.com/ParkerHwang/OpenSocrates/compare/v1.1.1...v1.1.2
package/README.ko.md CHANGED
@@ -1,3 +1,7 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ParkerHwang/OpenSocrates/main/docs/assets/opensocrates-banner.jpg" alt="OpenSocrates" width="820">
3
+ </p>
4
+
1
5
  # OpenSocrates
2
6
 
3
7
  [English](README.md) | **한국어**
@@ -12,19 +16,26 @@ OpenSocrates는 Claude와 Codex를 위한 로컬 연동 및 저작 추론 프레
12
16
  추론 시스템을 고른 뒤, 이론과 예제 전체를 활성 작업에 추가합니다. 단순한 사실
13
17
  확인과 기계적인 작업은 그대로 통과할 수 있습니다.
14
18
 
15
- 버전 `1.1.0`에는 48개의 추론 시스템과 Apple Silicon macOS
16
- (`darwin-arm64`)용 Claude 및 Codex 릴리스 패키지가 들어 있습니다. 기존 호스트
17
- 로그인을 사용하므로 API 키나 OpenSocrates 백엔드가 필요하지 않습니다.
19
+ 버전 `1.1.2`에는 48개의 추론 시스템, Claude의 단일 사용자 진입점, 선택된 절차를
20
+ 실제로 읽었는지 확인하는 Claude 접지 게이트, Claude/Codex 통합 라이프사이클,
21
+ 선택형 자동 업데이트가 들어 있습니다. 현재 릴리스 플랫폼은 Apple Silicon
22
+ macOS(`darwin-arm64`)입니다. 기존 호스트 로그인을 사용하므로 API 키나
23
+ OpenSocrates 백엔드가 필요하지 않습니다.
24
+
25
+ > **최신 릴리스: [OpenSocrates 1.1.2](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2).**
26
+ > 인증된 Claude 접지 영수증, 한 번으로 제한된 보정, 아티팩트 인스턴스에 결합된
27
+ > 재사용 방지를 추가했습니다. `npx --yes opensocrates@1.1.2 update --host all`로
28
+ > 관리 중인 두 호스트를 함께 업데이트할 수 있습니다.
18
29
 
19
30
  ## 호스트 지원 범위
20
31
 
21
- | 호스트 화면 | 자동 선택 | 추론 스킬 | 검증 상태 |
32
+ | 호스트 화면 | 자동 선택 | 사용자 진입점 | 검증 상태 |
22
33
  | --- | --- | --- | --- |
23
- | Codex CLI 및 Desktop | 지원 | 지원 | `darwin-arm64` 릴리스 검증 완료 |
24
- | Claude Code CLI | `UserPromptSubmit` 훅으로 지원 | 지원 | `darwin-arm64` 로컬 검증 완료 |
25
- | Claude Code 데스크톱 앱 | Claude Code 플러그인이 실행되는 곳에서 구현됨 | 지원 | 구현 완료, 실측 수신 기록 없음 |
26
- | Claude Cowork | 로컬 플러그인 런타임을 사용할 수 있을 때 구현됨 | 지원 | 실험적, 실측 수신 기록 없음 |
27
- | Claude 웹 및 Desktop Chat | 훅 미지원 | 플러그인 스킬로 지원 | 스킬 전용, 업로드 경로 미검증 |
34
+ | Codex CLI 및 Desktop | 지원 | OpenSocrates 플러그인 | `darwin-arm64` 릴리스 검증 완료 |
35
+ | Claude Code CLI | `UserPromptSubmit` 훅으로 지원 | `/opensocrates` | `darwin-arm64` 로컬 검증 완료 |
36
+ | Claude Code 데스크톱 앱 | Claude Code 플러그인이 실행되는 곳에서 구현됨 | `/opensocrates` | 구현 완료, 실측 수신 기록 없음 |
37
+ | Claude Cowork | 로컬 플러그인 런타임을 사용할 수 있을 때 구현됨 | `/opensocrates` | 실험적, 실측 수신 기록 없음 |
38
+ | Claude 웹 및 Desktop Chat | 훅 미지원 | `/opensocrates` | 스킬 전용, 업로드 경로 미검증 |
28
39
 
29
40
  상태 열은 서로 다른 네 단계를 뜻하며 같은 의미로 읽으면 안 됩니다.
30
41
 
@@ -59,47 +70,74 @@ Node.js 20 이상이 필요합니다. npm에 게시된 `opensocrates` 패키지
59
70
  내려받고 릴리스 체크섬과 모든 파일 체크섬을 검증한 뒤, 소유권 표식이 있는 관리형
60
71
  마켓플레이스를 등록합니다.
61
72
 
62
- ### Claude Code와 Cowork
73
+ ### 준비된 모든 호스트에 설치
63
74
 
64
75
  ```bash
65
- npx --yes opensocrates@1.1.0 install --host claude
76
+ npx --yes opensocrates@1.1.2 install --host all
66
77
  ```
67
78
 
68
- 라이프사이클 명령:
79
+ 모든 호스트 경로는 지원되는 인증 완료 CLI를 찾고, 어느 호스트도 바꾸기 전에
80
+ 전체 사전점검을 끝냅니다. 두 패키지를 모두 검증·스테이징한 다음 한 릴리스를
81
+ 트랜잭션으로 활성화합니다. 한 호스트의 활성화가 실패하면 이번 트랜잭션에서 이미
82
+ 바뀐 호스트도 이전 관리형 등록으로 되돌립니다.
83
+
84
+ 전체 라이프사이클에서 같은 호스트 값을 사용할 수 있습니다.
69
85
 
70
86
  ```bash
71
- npx --yes opensocrates@1.1.0 status --host claude
72
- npx --yes opensocrates@1.1.0 update --host claude
73
- npx --yes opensocrates@1.1.0 remove --host claude
87
+ npx --yes opensocrates@1.1.2 status --host all
88
+ npx --yes opensocrates@1.1.2 update --host all
89
+ npx --yes opensocrates@1.1.2 remove --host all
74
90
  ```
75
91
 
76
- ### Codex
92
+ 소유자 전용 `~/.opensocrates/desired-state.json`에는 선택 채널, 설치된 호스트,
93
+ 원하는 활성 버전이 기록됩니다. `status --host all`은 원하는 버전과 사용 가능한
94
+ 버전, 마지막 확인, 마지막 성공 자동 업데이트, 호스트별 버전 차이를 보여 줍니다.
95
+
96
+ ### 호스트 하나를 명시적으로 설치
77
97
 
78
98
  기존 사용자와의 호환성을 위해 기본 호스트는 계속 Codex입니다.
79
99
 
80
100
  ```bash
81
- npx --yes opensocrates@1.1.0 install
82
- # 같은 명령: npx --yes opensocrates@1.1.0 install --host codex
101
+ npx --yes opensocrates@1.1.2 install
102
+ # 같은 명령: npx --yes opensocrates@1.1.2 install --host codex
103
+ npx --yes opensocrates@1.1.2 install --host claude
83
104
  ```
84
105
 
85
- 라이프사이클 명령:
106
+ 기존 `--host codex` 및 `--host claude` 라이프사이클은 그대로 지원합니다. 호스트별
107
+ 업데이트는 의도적으로 버전 차이를 만들 수 있고, 이후 `update --host all` 또는
108
+ 성공한 자동 조정이 desired state에 기록된 모든 호스트를 다시 한 버전으로 맞춥니다.
109
+
110
+ ### 선택형 자동 업데이트
86
111
 
87
112
  ```bash
88
- npx --yes opensocrates@1.1.0 status --host codex
89
- npx --yes opensocrates@1.1.0 update --host codex
90
- npx --yes opensocrates@1.1.0 remove --host codex
113
+ npx --yes opensocrates@1.1.2 auto-update enable --host all
114
+ npx --yes opensocrates@1.1.2 auto-update status
115
+ npx --yes opensocrates@1.1.2 auto-update disable
91
116
  ```
92
117
 
93
- 두 호스트를 모두 사용하려면 설치 명령을 각각 실행하세요. 관리형 마켓플레이스는
94
- Claude와 Codex 설정 홈에 따로 저장됩니다.
118
+ 자동 업데이트는 명시적으로 켜기 전까지 비활성화되어 있습니다. macOS LaunchAgent는
119
+ 한 시간마다 가벼운 확인을 시작하고, desired state는 기본 24시간 간격과 지터,
120
+ 단일 실행 잠금을 적용합니다. 작업은 선택한 npm 채널을 호출하고 릴리스 및 패키지
121
+ 체크섬을 검증하며 모든 관리 호스트를 스테이징한 뒤 한 트랜잭션으로 조정합니다.
122
+ 메이저 버전 자동 업그레이드는 기본적으로 차단되며, 정책을 바꾸려면
123
+ `--allow-major`를 명시해야 합니다.
124
+
125
+ `auto-update enable`에 호스트 하나를 지정하면 자동 업데이트 대상만 좁아집니다.
126
+ 다른 설치 호스트를 desired state에서 제거하지 않으므로 `status --host all`은 모든
127
+ 설치를 계속 추적하고, 이후 `update --host all`도 전체 설치 집합을 다시 조정합니다.
128
+
129
+ 업데이터 영수증에는 버전, 시간, 호스트별 결과, 오류 범주만 기록됩니다. 프롬프트,
130
+ 대화 기록, 자격 증명, 작업공간 경로는 기록하지 않습니다. `auto-update disable`은
131
+ LaunchAgent를 언로드하고 삭제하며, `remove --host all`도 관리 호스트를 지우기 전에
132
+ 같은 정리를 수행합니다.
95
133
 
96
134
  ### Claude 웹 및 Desktop Chat 스킬
97
135
 
98
136
  이 화면들은 플러그인 스킬은 지원하지만 훅은 실행하지 않습니다. 릴리스에서
99
- `opensocrates-1.1.0-claude-chat-skills.zip`을 내려받아 Claude의 플러그인 사용자
100
- 설정 화면에서 업로드하세요. 작고 런타임이 없는 패키지에서 48개 방법 스킬과 3개
101
- 공용 스킬을 사용할 수 있지만 Chat은 플러그인 훅을 실행하지 않으므로 자동 선택은
102
- 없습니다. Anthropic의
137
+ `opensocrates-1.1.2-claude-chat-skills.zip`을 내려받아 Claude의 플러그인 사용자
138
+ 설정 화면에서 업로드하세요. 패키지는 `/opensocrates` 스킬 하나만 노출하고, 48개
139
+ 방법 절차와 엄격도·근거·추적 제어는 내부 참조로 둡니다. Chat은 플러그인 훅을
140
+ 실행하지 않으므로 자동 선택은 없습니다. Anthropic의
103
141
  [플러그인 화면 안내](https://support.claude.com/en/articles/13837440-use-plugins-in-claude)를
104
142
  참고하세요.
105
143
 
@@ -108,20 +146,21 @@ Claude와 Codex 설정 홈에 따로 저장됩니다.
108
146
  npm 레지스트리를 거치지 않을 때도 같은 호스트 옵션을 사용합니다.
109
147
 
110
148
  ```bash
111
- npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host claude
112
- npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host codex
149
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host all
150
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host claude
151
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host codex
113
152
  ```
114
153
 
115
154
  ### 릴리스 파일 직접 검증
116
155
 
117
- [v1.1.0 릴리스](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.0)에서
156
+ [v1.1.2 릴리스](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2)에서
118
157
  `opensocrates.mjs`, 호스트 패키지, `.sha256` 파일을 내려받습니다. Claude의 예:
119
158
 
120
159
  ```bash
121
- shasum -a 256 -c opensocrates-1.1.0-claude-plugin.zip.sha256
160
+ shasum -a 256 -c opensocrates-1.1.2-claude-plugin.zip.sha256
122
161
  node opensocrates.mjs install --host claude \
123
- --asset opensocrates-1.1.0-claude-plugin.zip \
124
- --checksum opensocrates-1.1.0-claude-plugin.zip.sha256
162
+ --asset opensocrates-1.1.2-claude-plugin.zip \
163
+ --checksum opensocrates-1.1.2-claude-plugin.zip.sha256
125
164
  ```
126
165
 
127
166
  Codex 패키지는 `claude`를 `codex`로 바꾸면 됩니다.
@@ -136,9 +175,13 @@ Codex 패키지는 `claude`를 `codex`로 바꾸면 됩니다.
136
175
  ```bash
137
176
  claude plugin uninstall opensocrates@OpenSocrates --scope user
138
177
  claude plugin marketplace remove OpenSocrates --scope user
139
- npx --yes opensocrates@1.1.0 install --host claude
178
+ npx --yes opensocrates@1.1.2 install --host claude
140
179
  ```
141
180
 
181
+ 관리형 v1.1.0 Claude 설치를 업데이트하면 패키지 트리 전체가 교체됩니다. 따라서
182
+ 예전의 최상위 방법 스킬 48개, `rigor`, `trace`, 중복 명령은 오래된 항목으로 남지
183
+ 않고 함께 제거됩니다.
184
+
142
185
  ## 사용법
143
186
 
144
187
  Claude나 Codex를 평소처럼 사용하세요. 요청에 판단, 해석, 진단, 설명, 계획,
@@ -148,12 +191,39 @@ Claude나 Codex를 평소처럼 사용하세요. 요청에 판단, 해석, 진
148
191
  1. 현재 호스트에서 새로운 비영구 셀렉터를 시작합니다.
149
192
  2. 저작된 48개 시스템 카탈로그에서 적합한 시스템을 선택합니다.
150
193
  3. 선택된 전체 콘텐츠를 소유자 전용 임시 Markdown 파일에 씁니다.
151
- 4. 활성 작업에 그 파일을 읽으라는 작은 숨김 컨텍스트를 추가합니다.
194
+ 4. 각 방법 ID와 콘텐츠 리비전, 크기 한도 안에 들면 정확한 `Do not use when` 및
195
+ `Stop conditions`를 작은 숨김 컨텍스트에 추가합니다.
196
+ 5. 활성 작업이 방법을 적용하기 전에 전체 파일을 읽고, 접지된 답변의 마지막에
197
+ `OpenSocrates grounding: triangulation@1`과 같은 정확한 감사 줄을 남기게 합니다.
198
+
199
+ Claude 훅 화면에서는 Read 전용 `PostToolUse` 훅이 현재 turn의 정확한 파일을 첫
200
+ 줄부터 종료 표식까지 읽은 경우에만 인증된 영수증을 만듭니다. `Stop` 시 영수증이나
201
+ 감사 줄이 없으면 한 번만 보정을 요청하고, `stop_hook_active`로 반복 보정을
202
+ 막습니다. 일부만 읽었거나 출력이 잘렸거나 실패했거나 다른 파일을 읽은 경우는
203
+ 인정하지 않습니다. Claude Chat은 이 훅을 실행하지 않으므로 접지 계약이 스킬
204
+ 지침으로만 적용됩니다.
205
+
206
+ 영수증은 해당 파일에 대한 성공한 `Read` 콜백이 종료 표식까지 도달한 내용을
207
+ 반환했다는 사실만 기록합니다. 모든 바이트가 전달되었음을 증명하지는 않으며,
208
+ 이 게이트는 실패 시 열린 상태로 통과합니다. 이 게이트가 방어하는 경계와 방어하지
209
+ 않는 범위는 [SECURITY.md](SECURITY.md)를 참고하세요.
152
210
 
153
211
  선택 수에는 고정 제한이 없습니다. 셀렉터의 내부 제한 시간은 30초이고 재시도하지
154
212
  않으며 실패 시 통과합니다. 타임아웃, 호스트 오류, 잘못된 출력, 미개입 결정,
155
213
  안전하지 않은 컨텍스트 또는 사용할 수 없는 훅은 모두 주입 없이 끝납니다.
156
214
 
215
+ Claude에서는 필요할 때 같은 컨트롤러를 명시적으로 호출할 수 있습니다.
216
+
217
+ ```text
218
+ /opensocrates <요청>
219
+ /opensocrates auto <요청>
220
+ /opensocrates trace
221
+ /opensocrates status
222
+ ```
223
+
224
+ Claude의 스킬·명령 UI에는 `/opensocrates` 하나만 나타납니다. 컨트롤러가 내부 방법
225
+ 참조를 선택해 읽으므로 사용자가 48개 구현 카탈로그를 직접 탐색할 필요가 없습니다.
226
+
157
227
  Claude 셀렉터는 세션을 저장하지 않는 단일 `claude --safe-mode -p` 프로세스를
158
228
  사용합니다. 안전 모드는 사용자, 프로젝트, 플러그인 커스터마이즈를 끕니다.
159
229
  `CLAUDE.md`, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령과 에이전트가 여기에
@@ -189,8 +259,16 @@ OpenSocrates는 백엔드를 호스팅하거나 텔레메트리를 추가하거
189
259
  임시 instruction 파일에는 OpenSocrates가 저작한 콘텐츠만 들어갑니다. 원시
190
260
  프롬프트, 대화 기록, 워크스페이스 파일, 도구 데이터, 자격 증명과 셀렉터 추론은
191
261
  OpenSocrates 기록, 로그, 메트릭, 진단 또는 instruction 파일에 쓰지 않습니다.
192
- `Stop`에서 현재 turn 파일을, `SessionEnd`에서 남은 세션 파일을,
193
- `SessionStart`에서 24시간이 지난 비정상 종료 잔여 파일을 삭제합니다.
262
+ 전체 Read 응답은 메모리에서 종료 표식만 확인하고 보관하지 않습니다. 소유자 전용
263
+ 접지 영수증에는 artifact 해시, 콘텐츠 리비전, 선택한 방법 ID, 키 기반 인증 및
264
+ 도구 사용 태그만 저장하며 프롬프트, 도구 출력, 워크스페이스 경로와 artifact 경로는
265
+ 저장하지 않습니다. `Stop`에서 현재 turn 파일과 영수증을, `SessionEnd`에서 남은
266
+ 세션 파일을, `SessionStart`에서 24시간이 지난 비정상 종료 잔여 파일을 삭제합니다.
267
+
268
+ 자동 업데이트를 켜면 앞서 설명한 desired state와 간결한 영수증만 소유자 전용
269
+ 권한으로 저장합니다. 실행 중인 Claude나 Codex 세션을 검사하거나 종료하지 않습니다.
270
+ 이미 실행 중인 작업은 로드한 플러그인을 계속 쓰고, 새 작업이 조정된 버전을 자연스럽게
271
+ 불러옵니다.
194
272
 
195
273
  취약점 신고와 측정된 지원 경계는 [SECURITY.md](SECURITY.md)를 확인하세요.
196
274
 
@@ -200,6 +278,11 @@ OpenSocrates 기록, 로그, 메트릭, 진단 또는 instruction 파일에 쓰
200
278
  [uv](https://docs.astral.sh/uv/), Python 3.12, Node.js 20 이상을 설치한 뒤 다음을
201
279
  실행합니다.
202
280
 
281
+ 릴리스 후보를 병합하기 전에는
282
+ [새 Apple Silicon Mac 인수 테스트 절차](docs/clean-machine-acceptance.ko.md)를 따라
283
+ 인증된 실제 Claude Code 및 Codex 홈에서 검증하고 개인정보를 뺀 근거 묶음을
284
+ 확보하세요.
285
+
203
286
  ```bash
204
287
  make bootstrap
205
288
  make format-check
package/README.md CHANGED
@@ -1,3 +1,7 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ParkerHwang/OpenSocrates/main/docs/assets/opensocrates-banner.jpg" alt="OpenSocrates" width="820">
3
+ </p>
4
+
1
5
  # OpenSocrates
2
6
 
3
7
  **English** | [한국어](README.ko.md)
@@ -13,19 +17,26 @@ uses a fresh host-native selector to choose relevant systems, and adds their
13
17
  complete theory and examples to the active task. Straightforward factual and
14
18
  mechanical work can pass through unchanged.
15
19
 
16
- Version `1.1.0` includes 48 reasoning systems and release packages for Claude
17
- and Codex on Apple-silicon macOS (`darwin-arm64`). It uses your existing host
18
- login and does not require an API key or an OpenSocrates backend.
20
+ Version `1.1.2` includes 48 reasoning systems, one user-facing Claude entry, a
21
+ Claude grounding gate that verifies selected procedures were read, coordinated
22
+ Claude/Codex lifecycle management, and opt-in automatic updates on
23
+ Apple-silicon macOS (`darwin-arm64`). It uses your existing host login and does
24
+ not require an API key or an OpenSocrates backend.
25
+
26
+ > **Latest release: [OpenSocrates 1.1.2](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2).**
27
+ > It adds authenticated Claude grounding receipts, one bounded repair pass,
28
+ > and artifact-instance-bound replay protection. Upgrade both managed hosts
29
+ > together with `npx --yes opensocrates@1.1.2 update --host all`.
19
30
 
20
31
  ## Host support
21
32
 
22
- | Host surface | Automatic selection | Reasoning skills | Validation status |
33
+ | Host surface | Automatic selection | User-facing entry | Validation status |
23
34
  | --- | --- | --- | --- |
24
- | Codex CLI and Desktop | Yes | Yes | Release-validated on `darwin-arm64` |
25
- | Claude Code CLI | Yes, through `UserPromptSubmit` | Yes | Locally validated on `darwin-arm64` |
26
- | Claude Code desktop app | Implemented, where Claude Code plugins run | Yes | Implemented; no live probe receipt |
27
- | Claude Cowork | Implemented, when the local plugin runtime is available | Yes | Experimental; no live probe receipt |
28
- | Claude web and Desktop Chat | No hooks | Yes, through plugin skills | Skills-only; upload path unvalidated |
35
+ | Codex CLI and Desktop | Yes | OpenSocrates plugin | Release-validated on `darwin-arm64` |
36
+ | Claude Code CLI | Yes, through `UserPromptSubmit` | `/opensocrates` | Locally validated on `darwin-arm64` |
37
+ | Claude Code desktop app | Implemented, where Claude Code plugins run | `/opensocrates` | Implemented; no live probe receipt |
38
+ | Claude Cowork | Implemented, when the local plugin runtime is available | `/opensocrates` | Experimental; no live probe receipt |
39
+ | Claude web and Desktop Chat | No hooks | `/opensocrates` | Skills-only; upload path unvalidated |
29
40
 
30
41
  The status column uses four distinct levels. Do not read them as
31
42
  interchangeable:
@@ -61,47 +72,79 @@ small, dependency-free installer. It downloads the matching package from
61
72
  GitHub Releases and verifies the release checksum and every file checksum
62
73
  before registering an owner-marked managed marketplace.
63
74
 
64
- ### Claude Code and Cowork
75
+ ### Install every ready host
65
76
 
66
77
  ```bash
67
- npx --yes opensocrates@1.1.0 install --host claude
78
+ npx --yes opensocrates@1.1.2 install --host all
68
79
  ```
69
80
 
70
- Lifecycle commands:
81
+ The all-host path detects supported, authenticated host CLIs, completes every
82
+ preflight before changing either host, verifies and stages both packages, and
83
+ then activates one release transactionally. If one activation fails, every
84
+ host already changed in that transaction is restored to its previous managed
85
+ registration.
86
+
87
+ Use the same host value for the complete lifecycle:
71
88
 
72
89
  ```bash
73
- npx --yes opensocrates@1.1.0 status --host claude
74
- npx --yes opensocrates@1.1.0 update --host claude
75
- npx --yes opensocrates@1.1.0 remove --host claude
90
+ npx --yes opensocrates@1.1.2 status --host all
91
+ npx --yes opensocrates@1.1.2 update --host all
92
+ npx --yes opensocrates@1.1.2 remove --host all
76
93
  ```
77
94
 
78
- ### Codex
95
+ A private `~/.opensocrates/desired-state.json` manifest records the selected
96
+ channel, installed hosts, and desired active version. `status --host all`
97
+ reports the desired and available versions, last check, last successful
98
+ automatic update, and per-host drift.
99
+
100
+ ### Install one host explicitly
79
101
 
80
102
  Codex remains the default host for backward compatibility:
81
103
 
82
104
  ```bash
83
- npx --yes opensocrates@1.1.0 install
84
- # Equivalent: npx --yes opensocrates@1.1.0 install --host codex
105
+ npx --yes opensocrates@1.1.2 install
106
+ # Equivalent: npx --yes opensocrates@1.1.2 install --host codex
107
+ npx --yes opensocrates@1.1.2 install --host claude
85
108
  ```
86
109
 
87
- Lifecycle commands:
110
+ Existing `--host codex` and `--host claude` lifecycle commands remain
111
+ supported. A host-specific update can intentionally create drift; a later
112
+ `update --host all` or successful automatic reconciliation brings every host
113
+ recorded in desired state back to one version.
114
+
115
+ ### Opt-in automatic updates
88
116
 
89
117
  ```bash
90
- npx --yes opensocrates@1.1.0 status --host codex
91
- npx --yes opensocrates@1.1.0 update --host codex
92
- npx --yes opensocrates@1.1.0 remove --host codex
118
+ npx --yes opensocrates@1.1.2 auto-update enable --host all
119
+ npx --yes opensocrates@1.1.2 auto-update status
120
+ npx --yes opensocrates@1.1.2 auto-update disable
93
121
  ```
94
122
 
95
- To use both hosts, run both install commands. Their managed marketplaces live
96
- under their respective Claude and Codex configuration homes.
123
+ Automatic updates are disabled until explicitly enabled. The macOS LaunchAgent
124
+ starts a bounded hourly poll; desired state applies the configured interval
125
+ (24 hours by default) with jitter and a single-instance lock. The job invokes
126
+ the selected npm channel, verifies release and package checksums, stages every
127
+ managed host, and reconciles them as one transaction. Major-version upgrades
128
+ are blocked by default; use `--allow-major` only when that policy is intended.
129
+
130
+ Passing one host to `auto-update enable` narrows only the automatic-update
131
+ scope. It never removes another installed host from desired state;
132
+ `status --host all` continues to track every installation, and a later
133
+ `update --host all` still reconciles the complete installed set.
134
+
135
+ The updater keeps a private receipt with version, time, per-host result, and an
136
+ error category only. It never records prompts, transcripts, credentials, or
137
+ workspace paths. `auto-update disable` unloads and removes the LaunchAgent;
138
+ `remove --host all` does the same before removing the managed hosts.
97
139
 
98
140
  ### Claude web and Desktop Chat skills
99
141
 
100
142
  These surfaces support plugin skills but not hooks. Download
101
- `opensocrates-1.1.0-claude-chat-skills.zip` from the release and upload it from
102
- Claude's plugin customization UI. The 48 method skills and three shared skills
103
- remain available in a small, runtime-free package, while automatic selection
104
- is absent because Chat does not execute plugin hooks. See Anthropic's
143
+ `opensocrates-1.1.2-claude-chat-skills.zip` from the release and upload it from
144
+ Claude's plugin customization UI. The package exposes exactly one
145
+ `/opensocrates` skill; its 48 method procedures, rigor, evidence, and trace
146
+ controls are internal supporting references. Automatic selection is absent
147
+ because Chat does not execute plugin hooks. See Anthropic's
105
148
  [plugin surface guide](https://support.claude.com/en/articles/13837440-use-plugins-in-claude).
106
149
 
107
150
  ### Install from a tagged GitHub source
@@ -109,21 +152,22 @@ is absent because Chat does not execute plugin hooks. See Anthropic's
109
152
  The same host option works without the npm registry:
110
153
 
111
154
  ```bash
112
- npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host claude
113
- npx --yes github:ParkerHwang/OpenSocrates#v1.1.0 install --host codex
155
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host all
156
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host claude
157
+ npx --yes github:ParkerHwang/OpenSocrates#v1.1.2 install --host codex
114
158
  ```
115
159
 
116
160
  ### Manual release verification
117
161
 
118
162
  Download `opensocrates.mjs`, the host package, and its `.sha256` file from the
119
- [v1.1.0 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.0).
163
+ [v1.1.2 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2).
120
164
  For Claude, for example:
121
165
 
122
166
  ```bash
123
- shasum -a 256 -c opensocrates-1.1.0-claude-plugin.zip.sha256
167
+ shasum -a 256 -c opensocrates-1.1.2-claude-plugin.zip.sha256
124
168
  node opensocrates.mjs install --host claude \
125
- --asset opensocrates-1.1.0-claude-plugin.zip \
126
- --checksum opensocrates-1.1.0-claude-plugin.zip.sha256
169
+ --asset opensocrates-1.1.2-claude-plugin.zip \
170
+ --checksum opensocrates-1.1.2-claude-plugin.zip.sha256
127
171
  ```
128
172
 
129
173
  Replace `claude` with `codex` for the Codex package.
@@ -138,9 +182,13 @@ what is installed, remove it explicitly:
138
182
  ```bash
139
183
  claude plugin uninstall opensocrates@OpenSocrates --scope user
140
184
  claude plugin marketplace remove OpenSocrates --scope user
141
- npx --yes opensocrates@1.1.0 install --host claude
185
+ npx --yes opensocrates@1.1.2 install --host claude
142
186
  ```
143
187
 
188
+ Updating a managed v1.1.0 Claude installation replaces the complete package
189
+ tree. Its old 48 top-level method skills, `rigor`, `trace`, and duplicate
190
+ commands are therefore removed rather than left visible as stale entries.
191
+
144
192
  ## Use
145
193
 
146
194
  Use Claude or Codex normally. Before a submitted prompt, OpenSocrates may
@@ -151,14 +199,43 @@ reasoning process. When it intervenes, it:
151
199
  1. starts a fresh, non-persistent selector in the current host;
152
200
  2. chooses from the authored 48-system catalog;
153
201
  3. writes the complete selected content to an owner-only temporary Markdown
154
- file; and
155
- 4. adds a small hidden context message telling the active task to read it.
202
+ file;
203
+ 4. adds a bounded hidden context message with each method ID, content revision,
204
+ and, when they fit, its exact `Do not use when` and `Stop conditions`; and
205
+ 5. requires the active task to read the complete file before applying the
206
+ method and to end a grounded response with an exact audit line such as
207
+ `OpenSocrates grounding: triangulation@1`.
208
+
209
+ On Claude hook surfaces, a Read-only `PostToolUse` hook records an authenticated
210
+ receipt only when the exact current-turn file is read from its first line
211
+ through a terminal marker. At `Stop`, a missing receipt or audit line requests
212
+ one bounded repair pass; `stop_hook_active` prevents a continuation loop. A
213
+ partial, truncated, failed, or wrong-file read is not accepted. Claude Chat
214
+ does not run these hooks, so its grounding contract remains skills-only.
215
+
216
+ The receipt records that a successful `Read` callback for that exact file
217
+ returned content reaching the terminal marker. It is not a proof that every byte
218
+ was delivered, and the gate fails open. See [SECURITY.md](SECURITY.md) for the
219
+ boundary this does and does not defend.
156
220
 
157
221
  There is no fixed selection-count limit. The selector has a 30-second internal
158
222
  deadline, does not retry, and fails open. A timeout, host error, invalid output,
159
223
  non-intervention decision, unsafe context, or unavailable hook produces no
160
224
  injection and does not block the user's task.
161
225
 
226
+ On Claude, explicitly invoke the same controller when desired:
227
+
228
+ ```text
229
+ /opensocrates <request>
230
+ /opensocrates auto <request>
231
+ /opensocrates trace
232
+ /opensocrates status
233
+ ```
234
+
235
+ Only `/opensocrates` appears in Claude's skill and command UI. The controller
236
+ selects and loads internal method references; users do not need to browse the
237
+ 48-system implementation catalog.
238
+
162
239
  The Claude selector uses one `claude --safe-mode -p` process with no session
163
240
  persistence. Safe mode disables user, project, and plugin customizations:
164
241
  `CLAUDE.md`, skills, plugins, hooks, MCP servers, custom commands, and agents.
@@ -195,10 +272,19 @@ telemetry, store an API key, or execute the user's requested task.
195
272
  Temporary instruction files contain authored OpenSocrates content only. Raw
196
273
  prompts, transcripts, workspace files, tool data, credentials, and selector
197
274
  reasoning are not written to OpenSocrates records, logs, metrics, diagnostics,
198
- or instruction files. Turn files are removed on `Stop`, remaining session
199
- files on `SessionEnd`, and crash leftovers older than 24 hours on
275
+ or instruction files. The complete Read response is inspected only in memory
276
+ for its terminal marker and is not retained. The owner-only grounding receipt
277
+ stores only an artifact digest, content revision, selected method IDs, and
278
+ keyed authentication/tool-use tags—never a prompt, tool output, workspace path,
279
+ or artifact path. Turn files and receipts are removed on `Stop`, remaining
280
+ session files on `SessionEnd`, and crash leftovers older than 24 hours on
200
281
  `SessionStart`.
201
282
 
283
+ When enabled, the updater stores only desired lifecycle state and the concise
284
+ receipt described above, under owner-only permissions. It does not inspect or
285
+ terminate running Claude or Codex sessions; a running task keeps its loaded
286
+ plugin, and a new task naturally loads the reconciled version.
287
+
202
288
  See [SECURITY.md](SECURITY.md) for vulnerability reporting and the measured
203
289
  support boundary.
204
290
 
@@ -208,6 +294,11 @@ The source repository intentionally excludes native binaries and intermediate
208
294
  build output. Install [uv](https://docs.astral.sh/uv/), Python 3.12, and Node.js
209
295
  20 or later, then run:
210
296
 
297
+ Before merging a release candidate, follow the
298
+ [clean Apple-silicon Mac acceptance procedure](docs/clean-machine-acceptance.md)
299
+ to exercise the real authenticated Claude Code and Codex homes and return a
300
+ privacy-safe evidence bundle.
301
+
211
302
  ```bash
212
303
  make bootstrap
213
304
  make format-check