opensocrates 1.0.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 +132 -0
  2. package/README.ko.md +224 -78
  3. package/README.md +237 -84
  4. package/SECURITY.md +71 -5
  5. package/VERSION +1 -1
  6. package/installer/opensocrates.mjs +1641 -190
  7. package/package.json +6 -3
package/CHANGELOG.md CHANGED
@@ -3,6 +3,135 @@
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
+
82
+ ## [1.1.0] - 2026-08-06
83
+
84
+ ### Added
85
+
86
+ - Claude Code CLI integration through native Claude plugin hooks and generated
87
+ reasoning skills. Claude Code desktop and Cowork use the same implemented
88
+ mechanism, but live delivery on those surfaces remains unvalidated.
89
+ - A bounded `claude --safe-mode -p` selector that uses the existing Claude login,
90
+ disables tools and project/plugin context, accepts only structured output,
91
+ and fails open after the existing 30-second deadline.
92
+ - Host-specific `npx` lifecycle support through `--host claude` while keeping
93
+ Codex as the backward-compatible default.
94
+ - A separate Claude release package, checksum verification, security boundary
95
+ checks, and offline integration contracts.
96
+ - A compact, runtime-free Claude Chat ZIP containing 48 method skills and
97
+ three shared skills for custom-plugin upload.
98
+ - A support matrix that distinguishes automatic local hooks from skills-only
99
+ Claude web and Desktop Chat use.
100
+
101
+ ### Fixed
102
+
103
+ - The packaged POSIX and PowerShell launchers now resolve the native runtime
104
+ from the plugin root (`runtime/<target>/...`) instead of from their own
105
+ `bin/` directory. Previously every packaged Claude and Codex hook took the
106
+ fail-open `missing_runtime` path, so `UserPromptSubmit` selection and
107
+ `Stop`/`SessionEnd` cleanup were silent no-ops in the generated packages
108
+ ([#16](https://github.com/ParkerHwang/OpenSocrates/issues/16)).
109
+
110
+ ### Changed
111
+
112
+ - The release gate now executes the generated packages' own launchers against
113
+ the packaged runtime layout for Claude and Codex, covering hook dispatch,
114
+ control mode, and the fail-open paths, and it inspects the generated Claude
115
+ package README for its trust-boundary and validation limitations
116
+ ([#16](https://github.com/ParkerHwang/OpenSocrates/issues/16),
117
+ [#22](https://github.com/ParkerHwang/OpenSocrates/issues/22)).
118
+ - The Claude package README now states that safe mode leaves managed settings
119
+ policy in force, that policy-configured hooks can still observe the selector
120
+ prompt and influence selection, and it grades Claude Code Desktop, Cowork,
121
+ and Claude Chat validation the same way the repository README does
122
+ ([#22](https://github.com/ParkerHwang/OpenSocrates/issues/22)).
123
+ - Release assembly, SBOM input, security scans, and GitHub Release publishing
124
+ now cover both Claude and Codex packages.
125
+ - The installer detects case-sensitive pre-1.0 Claude marketplace
126
+ registrations and requires an explicit migration instead of deleting them.
127
+
128
+ ### Security and privacy
129
+
130
+ - Claude selection receives only the current prompt and authored catalog; it
131
+ cannot read the transcript, workspace, MCP servers, or tools.
132
+ - Claude CLI stdout is parsed in memory, stderr is discarded, prompt history
133
+ is disabled, and the process group is terminated on timeout or shutdown.
134
+
6
135
  ## [1.0.0] - 2026-07-31
7
136
 
8
137
  ### Added
@@ -36,3 +165,6 @@ All notable changes to OpenSocrates are documented here. This project follows
36
165
  delivery remain explicitly unvalidated.
37
166
 
38
167
  [1.0.0]: https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0
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) | **한국어**
@@ -7,114 +11,239 @@
7
11
  [![Release](https://img.shields.io/github/v/release/ParkerHwang/OpenSocrates)](https://github.com/ParkerHwang/OpenSocrates/releases)
8
12
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
13
 
10
- OpenSocrates는 AI 에이전트 호스트를 위한 로컬 추론 프레임워크입니다. 의도적인
11
- 추론이 필요한 요청을 감지하고, 별도의 Codex 컨텍스트에서 적합한 추론 시스템을
12
- 선택한 뒤, 저작된 이론과 예제를 활성 작업에 추가합니다. 단순한 사실 확인과
13
- 기계적인 작업은 그대로 통과할 수 있습니다.
14
-
15
- 버전 `1.0.0`에는 48개의 추론 시스템이 들어 있으며 Apple Silicon macOS
16
- (`darwin-arm64`)의 Codex Desktop과 Codex CLI를 지원합니다. 다른 플랫폼,
17
- 바이너리 서명, 공증, 클린 머신 설치는 아직 검증됐다고 주장하지 않습니다.
14
+ OpenSocrates는 Claude와 Codex를 위한 로컬 연동 및 저작 추론 프레임워크입니다.
15
+ 의도적인 추론이 필요한 요청을 감지하고, 현재 호스트의 새로운 셀렉터에서 적합한
16
+ 추론 시스템을 고른 뒤, 이론과 예제 전체를 활성 작업에 추가합니다. 단순한 사실
17
+ 확인과 기계적인 작업은 그대로 통과할 수 있습니다.
18
+
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
+ > 관리 중인 두 호스트를 함께 업데이트할 수 있습니다.
29
+
30
+ ## 호스트 지원 범위
31
+
32
+ | 호스트 화면 | 자동 선택 | 사용자 진입점 | 검증 상태 |
33
+ | --- | --- | --- | --- |
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` | 스킬 전용, 업로드 경로 미검증 |
39
+
40
+ 상태 열은 서로 다른 네 단계를 뜻하며 같은 의미로 읽으면 안 됩니다.
41
+
42
+ - **구현 완료** — 코드에 존재하고 패키지에 포함됩니다.
43
+ - **로컬 검증 완료** — 관리자 장비에서 전 구간을 실행했지만 매 빌드마다
44
+ 검증하지는 않습니다.
45
+ - **릴리스 검증 완료** — 릴리스 게이트가 매 빌드마다 실행합니다.
46
+ - **실험적 / 실측 수신 기록 없음** — 구현은 되어 있지만 호스트가 실제로 훅을
47
+ 전달했다는 기록이 없습니다. `os capabilities show`는 이 항목들을 사용 가능이
48
+ 아니라 `unknown`으로 보고합니다.
49
+
50
+ Claude Chat 화면은 플러그인 훅을 실행하지 않습니다. 생성된 스킬은 사용할 수
51
+ 있지만, 프롬프트마다 자동으로 선택하는 기능은 플러그인 런타임을 실행하는 Claude
52
+ Code와 Cowork 화면에서만 작동합니다. 훅이나 셀렉터를 사용할 수 없으면
53
+ OpenSocrates는 작업을 막지 않고 통과합니다.
54
+
55
+ Cowork에는 아직 확인되지 않은 전제가 하나 더 있습니다. OpenSocrates는
56
+ `claude plugin marketplace add --scope user`로 마켓플레이스를 등록하며 이는
57
+ Claude Code 사용자 설정에 기록됩니다. Anthropic 문서는 Cowork에서 플러그인 훅이
58
+ 실행된다고 밝히지만, Claude Code CLI로 등록한 마켓플레이스가 Cowork에서 보인다는
59
+ 내용은 없습니다. 실측 기록이 생기기 전까지 Cowork는 실험적 상태로 두세요.
18
60
 
19
61
  ## 설치
20
62
 
21
- 설치 전에 OAuth로 Codex에 로그인하고 `codex` 명령을 사용할 수 있는지
22
- 확인하세요.
63
+ 설치 전에 호스트에 로그인하고 명령을 사용할 수 있는지 확인하세요.
64
+
65
+ - Claude: Claude Code `2.1.205` 이상과 `claude` 명령
66
+ - Codex: OAuth 로그인이 완료된 `codex` 명령
23
67
 
24
- ### 방법 1: npm에서 npx로 설치
68
+ Node.js 20 이상이 필요합니다. npm에 게시된 `opensocrates` 패키지는 외부
69
+ 의존성이 없는 작은 설치 프로그램입니다. GitHub Releases에서 호스트 패키지를
70
+ 내려받고 릴리스 체크섬과 모든 파일 체크섬을 검증한 뒤, 소유권 표식이 있는 관리형
71
+ 마켓플레이스를 등록합니다.
25
72
 
26
- Node.js 20 이상이 필요합니다. npm 패키지는 외부 의존성이 없는 작은 설치
27
- 프로그램이며, 일치하는 패키지를 GitHub Releases에서 내려받아 검증합니다.
73
+ ### 준비된 모든 호스트에 설치
28
74
 
29
75
  ```bash
30
- npx --yes opensocrates@1.0.0 install
76
+ npx --yes opensocrates@1.1.2 install --host all
31
77
  ```
32
78
 
33
- 라이프사이클 명령:
79
+ 모든 호스트 경로는 지원되는 인증 완료 CLI를 찾고, 어느 호스트도 바꾸기 전에
80
+ 전체 사전점검을 끝냅니다. 두 패키지를 모두 검증·스테이징한 다음 한 릴리스를
81
+ 트랜잭션으로 활성화합니다. 한 호스트의 활성화가 실패하면 이번 트랜잭션에서 이미
82
+ 바뀐 호스트도 이전 관리형 등록으로 되돌립니다.
83
+
84
+ 전체 라이프사이클에서 같은 호스트 값을 사용할 수 있습니다.
34
85
 
35
86
  ```bash
36
- npx --yes opensocrates@1.0.0 status
37
- npx --yes opensocrates@1.0.0 update
38
- npx --yes opensocrates@1.0.0 remove
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
39
90
  ```
40
91
 
41
- ### 방법 2: GitHub에서 npx로 설치
92
+ 소유자 전용 `~/.opensocrates/desired-state.json`에는 선택 채널, 설치된 호스트,
93
+ 원하는 활성 버전이 기록됩니다. `status --host all`은 원하는 버전과 사용 가능한
94
+ 버전, 마지막 확인, 마지막 성공 자동 업데이트, 호스트별 버전 차이를 보여 줍니다.
95
+
96
+ ### 호스트 하나를 명시적으로 설치
42
97
 
43
- Node.js 20 이상이 필요합니다. npm 레지스트리에 별도 패키지를 게시하지 않아도
44
- 태그가 고정된 GitHub 저장소에서 직접 설치합니다.
98
+ 기존 사용자와의 호환성을 위해 기본 호스트는 계속 Codex입니다.
45
99
 
46
100
  ```bash
47
- npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 install
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
48
104
  ```
49
105
 
50
- 라이프사이클 명령:
106
+ 기존 `--host codex` 및 `--host claude` 라이프사이클은 그대로 지원합니다. 호스트별
107
+ 업데이트는 의도적으로 버전 차이를 만들 수 있고, 이후 `update --host all` 또는
108
+ 성공한 자동 조정이 desired state에 기록된 모든 호스트를 다시 한 버전으로 맞춥니다.
109
+
110
+ ### 선택형 자동 업데이트
51
111
 
52
112
  ```bash
53
- npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 status
54
- npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 update
55
- npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 remove
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
56
116
  ```
57
117
 
58
- 설치 프로그램은 일치하는 GitHub Release 자산을 내려받고 릴리스 체크섬과
59
- 패키지 내부의 모든 체크섬을 검증한 다음, 현재 Codex 홈 아래의 비공개 관리형
60
- 마켓플레이스에 등록합니다.
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
+ 같은 정리를 수행합니다.
133
+
134
+ ### Claude 웹 및 Desktop Chat 스킬
135
+
136
+ 이 화면들은 플러그인 스킬은 지원하지만 훅은 실행하지 않습니다. 릴리스에서
137
+ `opensocrates-1.1.2-claude-chat-skills.zip`을 내려받아 Claude의 플러그인 사용자
138
+ 설정 화면에서 업로드하세요. 패키지는 `/opensocrates` 스킬 하나만 노출하고, 48개
139
+ 방법 절차와 엄격도·근거·추적 제어는 내부 참조로 둡니다. Chat은 플러그인 훅을
140
+ 실행하지 않으므로 자동 선택은 없습니다. Anthropic의
141
+ [플러그인 화면 안내](https://support.claude.com/en/articles/13837440-use-plugins-in-claude)를
142
+ 참고하세요.
61
143
 
62
- ### 방법 3: GitHub Releases에서 직접 다운로드
144
+ ### 태그가 고정된 GitHub 소스에서 설치
63
145
 
64
- [v1.0.0 릴리스](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0)에서
65
- `opensocrates.mjs`를 내려받은 뒤 실행합니다.
146
+ npm 레지스트리를 거치지 않을 때도 같은 호스트 옵션을 사용합니다.
66
147
 
67
148
  ```bash
68
- node opensocrates.mjs install
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
69
152
  ```
70
153
 
71
- 파일과 체크섬을 직접 내려받아 확인하려면:
154
+ ### 릴리스 파일 직접 검증
155
+
156
+ [v1.1.2 릴리스](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.1.2)에서
157
+ `opensocrates.mjs`, 호스트 패키지, `.sha256` 파일을 내려받습니다. Claude의 예:
72
158
 
73
159
  ```bash
74
- curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip
75
- curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip.sha256
76
- shasum -a 256 -c opensocrates-1.0.0-codex-plugin.zip.sha256
77
- node opensocrates.mjs install \
78
- --asset opensocrates-1.0.0-codex-plugin.zip \
79
- --checksum opensocrates-1.0.0-codex-plugin.zip.sha256
160
+ shasum -a 256 -c opensocrates-1.1.2-claude-plugin.zip.sha256
161
+ node opensocrates.mjs install --host claude \
162
+ --asset opensocrates-1.1.2-claude-plugin.zip \
163
+ --checksum opensocrates-1.1.2-claude-plugin.zip.sha256
80
164
  ```
81
165
 
82
- ### 방법 4: 소스에서 빌드해 설치
166
+ Codex 패키지는 `claude`를 `codex`로 바꾸면 됩니다.
167
+
168
+ ### 1.0 이전 Claude 플러그인에서 이전하기
83
169
 
84
- [uv](https://docs.astral.sh/uv/)와 Python 3.12가 필요합니다.
170
+ 일부 개발 버전은 대소문자를 구분하는 `OpenSocrates` 마켓플레이스 이름을
171
+ 사용했습니다. 새 이름은 `opensocrates`입니다. 설치 프로그램은 구형 등록을
172
+ 감지하지만 자동으로 지우지 않습니다. 설치된 항목을 확인한 뒤 명시적으로
173
+ 제거하세요.
85
174
 
86
175
  ```bash
87
- git clone https://github.com/ParkerHwang/OpenSocrates.git
88
- cd OpenSocrates
89
- uv python install 3.12
90
- uv sync --locked --all-groups
91
- make release-check
92
- uv run --locked --no-sync python tools/codex_plugin.py install
176
+ claude plugin uninstall opensocrates@OpenSocrates --scope user
177
+ claude plugin marketplace remove OpenSocrates --scope user
178
+ npx --yes opensocrates@1.1.2 install --host claude
93
179
  ```
94
180
 
95
- `make release-check`는 네이티브 런타임과 설치 가능한 패키지를 로컬에서
96
- 빌드합니다. 생성 파일은 Git에서 제외된 `build/`와 `dist/`에 기록됩니다.
181
+ 관리형 v1.1.0 Claude 설치를 업데이트하면 패키지 트리 전체가 교체됩니다. 따라서
182
+ 예전의 최상위 방법 스킬 48개, `rigor`, `trace`, 중복 명령은 오래된 항목으로 남지
183
+ 않고 함께 제거됩니다.
97
184
 
98
185
  ## 사용법
99
186
 
100
- Codex를 평소처럼 사용하세요. OpenSocrates는 제출된 각 프롬프트 전에 실행되며,
101
- 요청에 판단, 해석, 진단, 설명, 계획, 근거 조정 또는 다른 구조적 추론 과정이
102
- 필요할 때 개입할 수 있습니다. 개입 시 다음 순서로 동작합니다.
187
+ Claude나 Codex를 평소처럼 사용하세요. 요청에 판단, 해석, 진단, 설명, 계획,
188
+ 근거 조정 또는 다른 구조적 추론이 필요하면 OpenSocrates가 개입할 수 있습니다.
189
+ 개입할 때는 다음과 같이 동작합니다.
103
190
 
104
- 1. 매번 새로운 임시 셀렉터 스레드를 사용합니다.
191
+ 1. 현재 호스트에서 새로운 비영구 셀렉터를 시작합니다.
105
192
  2. 저작된 48개 시스템 카탈로그에서 적합한 시스템을 선택합니다.
106
- 3. 선택된 전체 콘텐츠를 소유자 전용 임시 Markdown 파일에 기록합니다.
107
- 4. 활성 작업에 해당 파일을 읽으라는 하나의 숨겨진 컨텍스트 메시지를
108
- 추가합니다.
109
-
110
- 선택 수에는 고정 제한이 없습니다. 훅 메시지는 작게 유지하면서 선택된 이론과
111
- 예제 전체는 압축하거나 자르지 않고 참조 파일에 보존합니다.
112
-
113
- 셀렉터의 내부 제한 시간은 30초이며 재시도하지 않고 실패 시 통과합니다.
114
- 타임아웃, SDK 오류, 잘못된 출력, 미개입 결정, 안전하지 않은 컨텍스트 또는
115
- 사용할 수 없는 훅은 모두 주입 없이 끝나며 사용자의 작업을 차단하지 않습니다.
193
+ 3. 선택된 전체 콘텐츠를 소유자 전용 임시 Markdown 파일에 씁니다.
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)를 참고하세요.
210
+
211
+ 선택 수에는 고정 제한이 없습니다. 셀렉터의 내부 제한 시간은 30초이고 재시도하지
212
+ 않으며 실패 시 통과합니다. 타임아웃, 호스트 오류, 잘못된 출력, 미개입 결정,
213
+ 안전하지 않은 컨텍스트 또는 사용할 수 없는 훅은 모두 주입 없이 끝납니다.
214
+
215
+ Claude에서는 필요할 때 같은 컨트롤러를 명시적으로 호출할 수 있습니다.
216
+
217
+ ```text
218
+ /opensocrates <요청>
219
+ /opensocrates auto <요청>
220
+ /opensocrates trace
221
+ /opensocrates status
222
+ ```
116
223
 
117
- 제한된 트랜스크립트 컨텍스트 요청도 막으려면:
224
+ Claude의 스킬·명령 UI에는 `/opensocrates` 하나만 나타납니다. 컨트롤러가 내부 방법
225
+ 참조를 선택해 읽으므로 사용자가 48개 구현 카탈로그를 직접 탐색할 필요가 없습니다.
226
+
227
+ Claude 셀렉터는 세션을 저장하지 않는 단일 `claude --safe-mode -p` 프로세스를
228
+ 사용합니다. 안전 모드는 사용자, 프로젝트, 플러그인 커스터마이즈를 끕니다.
229
+ `CLAUDE.md`, 스킬, 플러그인, 훅, MCP 서버, 사용자 정의 명령과 에이전트가 여기에
230
+ 해당합니다. OpenSocrates는 여기에 더해 `--tools ""`, `--disallowedTools "mcp__*"`,
231
+ `--strict-mcp-config`를 전달해 기본 도구와 MCP 도구가 남지 않도록 합니다.
232
+ 셀렉터에는 현재 프롬프트와 저작된 선택 카탈로그만 전달합니다.
233
+
234
+ 관리형 정책(managed policy) 설정은 호스트 신뢰 경계의 일부이며 안전 모드로
235
+ 비활성화되지 **않습니다**. Anthropic
236
+ [CLI 참조 문서](https://code.claude.com/docs/en/cli-reference)는 `--safe-mode`에서도
237
+ "관리형 설정 정책은 계속 적용되며 여기에는 정책으로 구성된 훅이 포함된다"고
238
+ 명시합니다. 관리자가 관리형 `UserPromptSubmit` 훅을 구성한 장비에서는 그 훅이
239
+ 셀렉터 프로세스 안에서 실행되고, 현재 프롬프트를 표준 입력으로 받으며,
240
+ `additionalContext`를 돌려주어 선택에 개입할 수 있습니다. 관리형 플러그인,
241
+ 관리형 스킬, 관리형 `CLAUDE.md`, 정책으로 구성된 MCP 서버는 로드되지 않습니다.
242
+ 조직이 관리형 훅을 구성한다면 셀렉터 프롬프트가 그 훅에 노출된다고 보고,
243
+ 허용할 수 없다면 OpenSocrates 선택 기능을 끄세요.
244
+
245
+ Codex 셀렉터는 제한된 대화 기록 컨텍스트를 추가로 사용할 수 있으며 다음 설정으로
246
+ 막을 수 있습니다.
118
247
 
119
248
  ```bash
120
249
  export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
@@ -122,22 +251,37 @@ export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
122
251
 
123
252
  ## 개인정보 보호와 보안
124
253
 
125
- OpenSocrates는 Codex 앱 서버와 사용자의 기존 Codex OAuth 세션을 통해 로컬에서
126
- 실행됩니다. API 키가 필요 없고, 백엔드를 호스팅하지 않으며, 사용자가 요청한
127
- 작업을 대신 실행하지 않고, 텔레메트리를 추가하지 않습니다.
254
+ OpenSocrates 연동은 로컬에서 실행되고 기존 Claude 또는 Codex 로그인을 사용합니다.
255
+ 다만 호스트 모델 요청은 해당 호스트 서비스의 약관에 따라 처리됩니다.
256
+ OpenSocrates는 백엔드를 호스팅하거나 텔레메트리를 추가하거나 API 키를 저장하거나
257
+ 사용자의 요청 작업을 대신 실행하지 않습니다.
128
258
 
129
259
  임시 instruction 파일에는 OpenSocrates가 저작한 콘텐츠만 들어갑니다. 원시
130
- 프롬프트, 대화 기록, 워크스페이스 파일, 도구 데이터, OAuth 자격 증명과 셀렉터
131
- 추론은 기록, 로그, 메트릭, 진단 또는 임시 instruction 파일에 저장되지
132
- 않습니다. `Stop`에서 현재 turn 파일을, `SessionEnd`에서 남은 세션 파일을,
133
- `SessionStart`에서 24시간이 지난 비정상 종료 잔여 파일을 삭제합니다.
260
+ 프롬프트, 대화 기록, 워크스페이스 파일, 도구 데이터, 자격 증명과 셀렉터 추론은
261
+ OpenSocrates 기록, 로그, 메트릭, 진단 또는 instruction 파일에 쓰지 않습니다.
262
+ 전체 Read 응답은 메모리에서 종료 표식만 확인하고 보관하지 않습니다. 소유자 전용
263
+ 접지 영수증에는 artifact 해시, 콘텐츠 리비전, 선택한 방법 ID, 키 기반 인증 및
264
+ 도구 사용 태그만 저장하며 프롬프트, 도구 출력, 워크스페이스 경로와 artifact 경로는
265
+ 저장하지 않습니다. `Stop`에서 현재 turn 파일과 영수증을, `SessionEnd`에서 남은
266
+ 세션 파일을, `SessionStart`에서 24시간이 지난 비정상 종료 잔여 파일을 삭제합니다.
267
+
268
+ 자동 업데이트를 켜면 앞서 설명한 desired state와 간결한 영수증만 소유자 전용
269
+ 권한으로 저장합니다. 실행 중인 Claude나 Codex 세션을 검사하거나 종료하지 않습니다.
270
+ 이미 실행 중인 작업은 로드한 플러그인을 계속 쓰고, 새 작업이 조정된 버전을 자연스럽게
271
+ 불러옵니다.
134
272
 
135
- 취약점 신고 방법과 현재 지원 경계는 [SECURITY.md](SECURITY.md)를 확인하세요.
273
+ 취약점 신고와 측정된 지원 경계는 [SECURITY.md](SECURITY.md)를 확인하세요.
136
274
 
137
275
  ## 개발
138
276
 
139
- 소스 저장소에는 네이티브 바이너리와 중간 빌드 결과를 넣지 않습니다. 잠긴 개발
140
- 환경을 설치하고 다음 검사를 실행합니다.
277
+ 소스 저장소에는 네이티브 바이너리와 중간 빌드 결과를 넣지 않습니다.
278
+ [uv](https://docs.astral.sh/uv/), Python 3.12, Node.js 20 이상을 설치한 뒤 다음을
279
+ 실행합니다.
280
+
281
+ 릴리스 후보를 병합하기 전에는
282
+ [새 Apple Silicon Mac 인수 테스트 절차](docs/clean-machine-acceptance.ko.md)를 따라
283
+ 인증된 실제 Claude Code 및 Codex 홈에서 검증하고 개인정보를 뺀 근거 묶음을
284
+ 확보하세요.
141
285
 
142
286
  ```bash
143
287
  make bootstrap
@@ -153,12 +297,11 @@ npm pack --dry-run
153
297
  make release-check
154
298
  ```
155
299
 
156
- 저장소 구조:
157
-
158
300
  | 경로 | 용도 |
159
301
  | --- | --- |
160
- | `src/opensocrates/` | Python 3.12 런타임과 셀렉터 소스 |
302
+ | `src/opensocrates/` | 공유 Python 3.12 런타임과 호스트별 셀렉터 |
161
303
  | `content/` | 정책, 다국어 메시지, 추론 방법, 이론과 예제 |
304
+ | `plugin-src/claude/` | Claude 플러그인 템플릿 |
162
305
  | `plugin-src/codex/` | Codex 플러그인 템플릿 |
163
306
  | `schemas/source/` | 정규 스키마 정의 |
164
307
  | `schemas/v1/` | 생성된 버전 고정 공개 스키마 |
@@ -180,3 +323,6 @@ make release-check
180
323
 
181
324
  OpenSocrates는 [MIT 라이선스](LICENSE)로 배포됩니다. 저작권 및 라이선스 고지를
182
325
  유지하면 사용, 수정, 배포, 재라이선스와 판매가 가능합니다.
326
+
327
+ OpenSocrates는 독립 오픈 소스 프로젝트이며 Anthropic 또는 OpenAI와 제휴하거나
328
+ 그들의 보증을 받은 프로젝트가 아닙니다.