sneakoscope 0.3.0 → 0.5.0

package/README.md

@@ -1,12 +1,17 @@
-# Sneakoscope Codex
+<p align="center">
+  <img src="docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
+</p>
 
-Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and optional GPT Image 2 visual cartridges.
+<h1 align="center">Sneakoscope Codex</h1>
+
+Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and deterministic GX visual context cartridges.
 
 ```bash
 npm i -g sneakoscope
 ```
 
 The npm package name is `sneakoscope`; the command is branded as SKS and exposed as lowercase `sks` for shell portability.
+Global installation is the default and recommended setup. For a project-only install, use `npm i -D sneakoscope` and initialize hooks with `npx sks init --install-scope project`; this writes hook commands that call the local `node_modules/sneakoscope` binary instead of global `sks`.
 
 `@openai/codex` is intentionally not bundled. Install Codex separately, or set `SKS_CODEX_BIN` to the Codex executable you want Sneakoscope Codex to supervise.
 
@@ -25,6 +30,14 @@ sks init
 sks selftest --mock
 ```
 
+Project-only setup:
+
+```bash
+npm i -D sneakoscope
+npx sks doctor --fix --install-scope project
+npx sks init --install-scope project
+```
+
 Create a Ralph mission:
 
 ```bash
@@ -47,15 +60,25 @@ For a local smoke test that does not call a model:
 sks ralph run latest --mock
 ```
 
+Run a research mission:
+
+```bash
+sks research prepare "LLM 에이전트의 새로운 평가 방법론"
+sks research run latest --max-cycles 3
+```
+
 ## What Sneakoscope Codex Adds
 
 - **Mandatory clarification**: `ralph prepare` generates required decision slots before autonomous execution can start.
 - **Sealed decision contract**: `ralph answer` validates answers and writes `decision-contract.json`.
 - **No-question Ralph loop**: after `ralph run` starts, Ralph must resolve ambiguity with the sealed contract instead of asking the user.
+- **Research mode**: `research` runs a frontier-discovery loop for non-obvious hypotheses, falsification, novelty ledgers, and testable experiments.
 - **Database guard**: destructive DB operations, production writes, unsafe Supabase MCP configuration, and direct live SQL mutations are blocked or warned on.
 - **H-Proof done gate**: completion requires supported critical claims, reviewed DB safety state, acceptable visual/wiki drift, and required test evidence.
+- **Performance evaluation**: `sks eval` produces deterministic token, accuracy-proxy, recall, support, and runtime metrics for before/after evidence.
 - **Bounded runtime state**: child process output is tailed, logs are rotated/compacted, and old mission artifacts can be pruned.
-- **Visual cartridges**: `gx` creates metadata-first visual cartridges where `vgraph.json` remains the source of truth and image generation is delegated to Codex/GPT Image 2.
+- **Visual cartridges**: `gx` creates deterministic SVG/HTML visual context from `vgraph.json` and `beta.json`; no generated-image service is required.
+- **Design artifact skill**: `sks init` installs a local skill for high-fidelity HTML/UI/prototype work with design-context gathering and rendered verification.
 
 ## Ralph Workflow
 
@@ -82,14 +105,14 @@ Core invariants:
 3. New ambiguity during `run` is resolved by the sealed decision ladder.
 4. Hooks help enforce the policy, but the Sneakoscope Codex supervisor and mission files remain the source of truth.
 5. Database destructive operations are never allowed.
-6. Generated images are not authoritative; `vgraph.json` is.
+6. Rendered GX files are reproducible context artifacts; `vgraph.json` is authoritative.
 7. Unsupported critical claims block completion.
 
 ## Commands
 
 ```bash
-sks doctor [--fix] [--json]
-sks init [--force]
+sks doctor [--fix] [--json] [--install-scope global|project]
+sks init [--force] [--install-scope global|project]
 sks selftest [--mock]
 
 sks ralph prepare "task"
@@ -97,6 +120,10 @@ sks ralph answer <mission-id|latest> <answers.json>
 sks ralph run <mission-id|latest> [--mock] [--max-cycles N]
 sks ralph status <mission-id|latest>
 
+sks research prepare "topic" [--depth frontier]
+sks research run <mission-id|latest> [--mock] [--max-cycles N]
+sks research status <mission-id|latest>
+
 sks db policy
 sks db scan [--migrations] [--json]
 sks db mcp-config --project-ref <ref> [--features database,docs]
@@ -106,9 +133,16 @@ sks db check --sql "SELECT * FROM users LIMIT 10"
 sks db check --command "supabase db reset"
 sks db check --file ./migration.sql
 
+sks eval run [--json] [--out report.json] [--iterations N]
+sks eval compare --baseline old.json --candidate new.json [--json]
+sks eval thresholds
+
 sks hproof check [mission-id|latest]
 sks gx init [name]
-sks gx render|validate|drift
+sks gx render [name] [--format svg|html|all]
+sks gx validate [name]
+sks gx drift [name]
+sks gx snapshot [name]
 sks profile show
 sks profile set <model>
 sks gc [--dry-run] [--json]
@@ -117,6 +151,32 @@ sks stats [--json]
 
 `sks memory` is currently an alias for garbage collection/retention handling.
 
+## Research Mode
+
+Research mode is for exploratory work where the desired output is a possible new insight, mechanism, prediction, or experiment, not a summary. It uses a frontier-discovery loop:
+
+```text
+R0 frame discovery criteria
+R1 map assumptions and baselines
+R2 generate competing hypotheses
+R3 falsify with counterexamples and missing evidence
+R4 synthesize surviving mechanisms
+R5 propose tests, predictions, or probes
+R6 write novelty ledger and research gate
+```
+
+Artifacts are written under `.sneakoscope/missions/<MISSION_ID>/`:
+
+```text
+research-plan.md
+research-plan.json
+research-report.md
+novelty-ledger.json
+research-gate.json
+```
+
+`sks research run` uses the `sks-research` Codex profile with maximum configured reasoning effort. `--mock` exercises the local artifact flow without calling a model.
+
 ## Database Safety
 
 Sneakoscope Codex treats database access as high risk across Supabase MCP, Supabase CLI, Postgres, Prisma, Drizzle, Knex, Sequelize, `psql`, SQL files, and MCP-shaped payloads.
@@ -165,6 +225,24 @@ sks db check --command "supabase db reset"
 
 Hooks are strongest for Codex tool execution paths, but Sneakoscope Codex does not rely on hooks alone. Ralph startup also scans DB/MCP configuration, and the supervised prompt embeds the DB policy.
 
+## Performance Evaluation
+
+`sks eval run` benchmarks the current SKS flow with a deterministic context-selection scenario. It compares an uncompressed all-claims baseline against the TriWiki compressed capsule and reports:
+
+```text
+estimated_tokens
+token_savings_pct
+accuracy_proxy
+required_recall
+relevance_precision
+support_ratio
+unsupported_critical_selected
+context_build_ms_per_run
+meaningful_improvement
+```
+
+`accuracy_proxy` is an evidence-weighted context quality metric, not a live model task score. Use `sks eval compare --baseline old.json --candidate new.json` to compare saved JSON reports across versions or experiments.
+
 ## H-Proof Done Gate
 
 Ralph completion is evaluated through `.sneakoscope/missions/<MISSION_ID>/done-gate.json`.
@@ -176,6 +254,8 @@ A mission cannot pass when:
 - a database safety violation or destructive DB attempt is recorded
 - DB safety logs exist but have not been reviewed
 - required tests lack evidence
+- required performance evaluation evidence is missing
+- required design verification evidence is missing
 - visual or wiki drift is marked `high`
 
 Run the evaluator directly with:
@@ -196,6 +276,15 @@ sks hproof check latest
 AGENTS.md             managed repository rules block
 ```
 
+Install scope controls `.codex/hooks.json`:
+
+```text
+global  -> sks hook ...
+project -> node ./node_modules/sneakoscope/bin/sks.mjs hook ...
+```
+
+If no scope is provided, SKS uses `global`.
+
 Storage is intentionally bounded:
 
 - process stdout/stderr are kept as bounded tails
@@ -217,20 +306,26 @@ This creates:
 ```text
 .sneakoscope/gx/cartridges/<name>/vgraph.json
 .sneakoscope/gx/cartridges/<name>/beta.json
-.sneakoscope/gx/cartridges/<name>/image-prompt.md
+.sneakoscope/gx/cartridges/<name>/render.svg
+.sneakoscope/gx/cartridges/<name>/render.html
+.sneakoscope/gx/cartridges/<name>/validation.json
+.sneakoscope/gx/cartridges/<name>/drift.json
 ```
 
-The intended flow is metadata first:
+The intended flow is source first and deterministic:
 
 ```text
 vgraph.json
-  -> image-prompt.md
-  -> Codex $imagegen / GPT Image 2
-  -> sheet.png
-  -> vision parse.json
-  -> validate against vgraph.json
+  + beta.json
+  -> sks gx render
+  -> render.svg / render.html
+  -> sks gx validate
+  -> sks gx drift
+  -> sks gx snapshot
 ```
 
+`render.svg` embeds the normalized `vgraph.json` hash. `sks gx drift` fails when the render is missing, stale, or structurally invalid.
+
 ## TriWiki Context Compression
 
 TriWiki is a harness-level context selection strategy, not a model-internal modification. It scores claims and memory entries by geometric distance, authority, freshness, risk, and token cost, then builds small context capsules for the current mission.
@@ -251,8 +346,11 @@ Q0 raw logs only when necessary
 bin/sks.mjs              CLI executable
 src/cli/main.mjs            command router and Ralph loop
 src/core/db-safety.mjs      SQL, CLI, and MCP payload classifier
+src/core/evaluation.mjs     token, accuracy-proxy, and context-quality evaluator
+src/core/gx-renderer.mjs    deterministic SVG/HTML visual context renderer
 src/core/hproof.mjs         done-gate evaluator
 src/core/init.mjs           project bootstrap and hook/skill installation
+src/core/research.mjs       research-mode plan, novelty ledger, and gate helpers
 src/core/retention.mjs      storage report and garbage collection policy
 src/core/triwiki-attention.mjs
 docs/PERFORMANCE.md         resource and leak policy
@@ -266,7 +364,10 @@ The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, a
 ```bash
 npm run packcheck
 npm run selftest
+npm run sizecheck
 npm run doctor
 ```
 
+`npm run sizecheck` blocks accidental package bloat before `npm pack` or `npm publish`. Defaults: packed tarball `<=96 KiB`, unpacked package `<=320 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Override only for an intentional release with `SKS_MAX_PACK_BYTES`, `SKS_MAX_UNPACKED_BYTES`, `SKS_MAX_PACK_FILES`, or `SKS_MAX_TRACKED_FILE_BYTES`.
+
 `npm run selftest` uses the mock path and does not call a model. Live Ralph runs require a working Codex CLI installation and authentication.

package/docs/PERFORMANCE.md

@@ -1,19 +1,42 @@
 # Sneakoscope Codex performance and leak policy
 
-Sneakoscope Codex v0.2 is designed to keep runtime, package size, RAM, and storage bounded.
+Sneakoscope Codex v0.5 is designed to keep runtime, package size, RAM, and storage bounded.
 
 ## Speed
 
 - `codex exec` output is streamed to files and only a bounded tail is retained in memory.
 - Ralph cycles run under a timeout and bounded max cycles.
 - TriWiki claim selection uses bounded top-K selection instead of sorting unbounded context into prompts.
+- GX visual context renders deterministic SVG/HTML from JSON sources, avoiding external image-generation latency, cost, and nondeterminism.
 - `sks gc` runs after Ralph cycles by default.
 
+## Evaluation metrics
+
+`sks eval run` creates a deterministic JSON report in `.sneakoscope/reports/` unless `--no-save` is used. The built-in scenario compares an uncompressed all-claims baseline with a TriWiki compressed context capsule.
+
+Tracked metrics:
+
+- `estimated_tokens`: deterministic chars/4 prompt-size estimate for local regression tracking
+- `token_savings_pct`: prompt-size reduction versus baseline
+- `accuracy_proxy`: evidence-weighted context-selection quality score
+- `required_recall`: required claim coverage
+- `relevance_precision`: selected required claims divided by selected claims
+- `support_ratio`: selected claims that are supported or weakly supported
+- `unsupported_critical_selected`: critical/high unsupported claims that survived compression
+- `context_build_ms_per_run`: local context construction runtime
+- `meaningful_improvement`: true only when token savings, accuracy delta, recall, unsupported-critical filtering, and runtime thresholds pass
+
+Default meaningful-improvement thresholds are intentionally explicit: at least 25% token savings, at least +0.03 accuracy-proxy delta, at least 0.95 required recall, zero unsupported critical claims selected, and candidate context construction under 25 ms per run. `sks eval compare --baseline old.json --candidate new.json` compares saved reports across implementations.
+
+The accuracy metric is not a live model task score. It is a deterministic proxy for whether the context handed to a model is smaller, better supported, and less contaminated by unsupported critical claims.
+
 ## Package size
 
 - The npm package has zero runtime dependencies.
 - `@openai/codex` is no longer bundled. Users install Codex separately or set `SKS_CODEX_BIN`.
 - Optional Rust source is in `crates/` for the Git repo, but is excluded from the npm package by the `files` allowlist.
+- GX rendering uses only built-in Node.js APIs and ships as source in the npm package.
+- `npm run sizecheck` enforces package limits before pack/publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
 
 ## Memory leaks
 
@@ -37,3 +60,9 @@ Rust is useful for CPU-heavy long-running kernels, but not for the default npm p
 Sneakoscope Codex v0.3 adds a DB Safety Guard without adding runtime dependencies. It scans hook payloads and CLI commands with bounded string traversal and blocks high-risk database operations before Codex can execute them.
 
 Blocked classes include destructive SQL, direct remote SQL mutation, `supabase db reset`, `supabase db push`, migration history repair/squash, and project/branch destructive commands. The guard is intentionally conservative: when unsure, it blocks or warns rather than allowing a potentially destructive database operation.
+
+## GX visual context policy
+
+Sneakoscope Codex v0.4 replaces model-rendered visual cartridges with deterministic code-rendered context sheets. `vgraph.json` and `beta.json` are the inputs, `render.svg` and `render.html` are reproducible outputs, and `drift.json` records whether the rendered source hash still matches the current graph.
+
+This keeps visual context cheap to regenerate, diffable in normal tooling, and safe to validate during npm packaging without network calls or model access.

package/docs/assets/sneakoscope-codex-logo.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">Sneakoscope Codex logo</title>
+  <desc id="desc">A brass magical danger-sensing lens with a red core, orbiting rings, and SKS initials.</desc>
+  <defs>
+    <radialGradient id="lens" cx="50%" cy="42%" r="58%">
+      <stop offset="0%" stop-color="#fff4c2"/>
+      <stop offset="42%" stop-color="#f0b54f"/>
+      <stop offset="100%" stop-color="#7b241f"/>
+    </radialGradient>
+    <linearGradient id="brass" x1="92" x2="420" y1="80" y2="432">
+      <stop offset="0%" stop-color="#ffe28a"/>
+      <stop offset="46%" stop-color="#c9872e"/>
+      <stop offset="100%" stop-color="#6c3218"/>
+    </linearGradient>
+    <linearGradient id="ink" x1="160" x2="352" y1="154" y2="358">
+      <stop offset="0%" stop-color="#311018"/>
+      <stop offset="100%" stop-color="#15070b"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#12070a" flood-opacity=".28"/>
+    </filter>
+  </defs>
+
+  <rect width="512" height="512" rx="108" fill="#16080d"/>
+  <path fill="#241016" d="M64 346c61 66 122 96 193 96 72 0 138-34 197-101v106c0 21-17 38-38 38H102c-21 0-38-17-38-38V346Z" opacity=".65"/>
+
+  <g filter="url(#shadow)">
+    <path fill="none" stroke="url(#brass)" stroke-width="16" stroke-linecap="round" d="M99 256c41-82 95-123 158-123 62 0 115 41 156 123-41 82-94 123-156 123-63 0-117-41-158-123Z"/>
+    <path fill="none" stroke="#f4c56a" stroke-width="5" stroke-linecap="round" d="M126 256c34-61 78-92 131-92 52 0 96 31 130 92-34 61-78 92-130 92-53 0-97-31-131-92Z" opacity=".86"/>
+
+    <circle cx="256" cy="256" r="93" fill="url(#brass)"/>
+    <circle cx="256" cy="256" r="74" fill="url(#ink)"/>
+    <circle cx="256" cy="256" r="56" fill="url(#lens)"/>
+    <circle cx="237" cy="236" r="16" fill="#fff8d8" opacity=".82"/>
+    <circle cx="283" cy="282" r="9" fill="#5b1017" opacity=".75"/>
+
+    <path fill="#fff0a4" d="M256 176l14 57 55-18-42 39 43 38-56-16-14 57-14-57-56 16 43-38-42-39 55 18 14-57Z"/>
+    <circle cx="256" cy="256" r="17" fill="#7b0f17"/>
+
+    <path fill="none" stroke="#f6d37c" stroke-width="11" stroke-linecap="round" d="M256 75v36M256 401v36M75 256h36M401 256h36"/>
+    <path fill="none" stroke="#b86232" stroke-width="8" stroke-linecap="round" d="M133 132l26 26M353 354l26 26M379 132l-26 26M159 354l-26 26"/>
+
+    <g fill="#fff0bc">
+      <circle cx="127" cy="113" r="7"/>
+      <circle cx="385" cy="113" r="7"/>
+      <circle cx="127" cy="399" r="7"/>
+      <circle cx="385" cy="399" r="7"/>
+    </g>
+  </g>
+
+</svg>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.3.0",
-  "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, GPT Image 2 workflow, and TriWiki compression.",
+  "version": "0.5.0",
+  "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, deterministic GX visual context, and TriWiki compression.",
   "type": "module",
   "bin": {
     "sks": "bin/sks.mjs"
@@ -20,18 +20,27 @@
   "scripts": {
     "selftest": "node ./bin/sks.mjs selftest --mock",
     "doctor": "node ./bin/sks.mjs doctor",
-    "packcheck": "find bin src -name '*.mjs' -print0 | xargs -0 -n1 node --check",
-    "prepack": "npm run packcheck && npm run selftest",
-    "prepublishOnly": "npm run packcheck && npm run selftest"
+    "packcheck": "find bin src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "sizecheck": "node ./scripts/sizecheck.mjs",
+    "prepack": "npm run packcheck && npm run selftest && npm run sizecheck",
+    "prepublishOnly": "npm run packcheck && npm run selftest && npm run sizecheck"
   },
   "keywords": [
+    "sneakoscope",
     "codex",
     "sks",
+    "cli",
     "ai-agent",
     "harness",
     "ralph",
+    "research",
+    "hypothesis",
+    "discovery",
     "llm-wiki",
-    "gpt-image-2",
+    "gx",
+    "svg",
+    "deterministic",
+    "visual-context",
     "resource-safe",
     "database-safe",
     "supabase-mcp",