sneakoscope 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DCODEX contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# Sneakoscope Codex
+
+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.
+
+```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.
+
+`@openai/codex` is intentionally not bundled. Install Codex separately, or set `SKS_CODEX_BIN` to the Codex executable you want Sneakoscope Codex to supervise.
+
+## Requirements
+
+- Node.js `>=20.11`
+- Codex CLI authentication for live Ralph runs
+- No runtime npm dependencies in the Sneakoscope Codex package
+- Optional Rust helper: compile `crates/sks-core` yourself and expose `sks-rs` on `PATH`, or set `SKS_RS_BIN`
+
+## Quick Start
+
+```bash
+sks doctor --fix
+sks init
+sks selftest --mock
+```
+
+Create a Ralph mission:
+
+```bash
+sks ralph prepare "결제 실패 재시도 로직 개선"
+```
+
+Answer every generated slot, seal the decision contract, then run:
+
+```bash
+cat .sneakoscope/missions/<MISSION_ID>/questions.md
+cp .sneakoscope/missions/<MISSION_ID>/required-answers.schema.json answers.json
+# edit answers.json
+sks ralph answer <MISSION_ID> answers.json
+sks ralph run <MISSION_ID> --max-cycles 8
+```
+
+For a local smoke test that does not call a model:
+
+```bash
+sks ralph run latest --mock
+```
+
+## 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.
+- **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.
+- **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.
+
+## Ralph Workflow
+
+```text
+ralph prepare
+  -> create mission
+  -> generate questions.md and required-answers.schema.json
+
+ralph answer
+  -> validate answers.json
+  -> seal decision-contract.json
+
+ralph run
+  -> activate no-question lock
+  -> scan database safety state
+  -> run supervised Codex cycles
+  -> evaluate done-gate.json
+```
+
+Core invariants:
+
+1. Ralph can ask questions only during `prepare`.
+2. `run` is locked until every required answer is supplied.
+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.
+7. Unsupported critical claims block completion.
+
+## Commands
+
+```bash
+sks doctor [--fix] [--json]
+sks init [--force]
+sks selftest [--mock]
+
+sks ralph prepare "task"
+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 db policy
+sks db scan [--migrations] [--json]
+sks db mcp-config --project-ref <ref> [--features database,docs]
+sks db classify --sql "DROP TABLE users"
+sks db classify --command "supabase db reset"
+sks db check --sql "SELECT * FROM users LIMIT 10"
+sks db check --command "supabase db reset"
+sks db check --file ./migration.sql
+
+sks hproof check [mission-id|latest]
+sks gx init [name]
+sks gx render|validate|drift
+sks profile show
+sks profile set <model>
+sks gc [--dry-run] [--json]
+sks stats [--json]
+```
+
+`sks memory` is currently an alias for garbage collection/retention handling.
+
+## 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.
+
+Always blocked:
+
+```text
+DROP DATABASE / SCHEMA / TABLE / VIEW / FUNCTION / TRIGGER / TYPE / EXTENSION
+TRUNCATE
+mass DELETE / UPDATE
+ALTER TABLE ... DROP / RENAME
+CREATE OR REPLACE
+DROP ... CASCADE
+GRANT / REVOKE
+DISABLE RLS
+supabase db reset / push
+supabase migration repair / squash
+project or branch delete/reset/merge commands
+production writes
+direct live writes through execute_sql
+```
+
+Allowed by default:
+
+```text
+SELECT, WITH ... SELECT, SHOW, EXPLAIN, DESCRIBE
+read-only, project-scoped Supabase MCP
+local or preview migration-file proposals when the sealed contract allows them
+```
+
+Recommended Supabase MCP URL shape:
+
+```text
+https://mcp.supabase.com/mcp?project_ref=<project_ref>&read_only=true&features=database,docs
+```
+
+Useful checks:
+
+```bash
+sks db policy
+sks db scan --migrations
+sks db mcp-config --project-ref <supabase_project_ref>
+sks db check --sql "DROP TABLE users"
+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.
+
+## H-Proof Done Gate
+
+Ralph completion is evaluated through `.sneakoscope/missions/<MISSION_ID>/done-gate.json`.
+
+A mission cannot pass when:
+
+- `decision-contract.json` is missing
+- unsupported critical claims are present
+- a database safety violation or destructive DB attempt is recorded
+- DB safety logs exist but have not been reviewed
+- required tests lack evidence
+- visual or wiki drift is marked `high`
+
+Run the evaluator directly with:
+
+```bash
+sks hproof check latest
+```
+
+## Runtime State
+
+`sks init` creates the local control surface:
+
+```text
+.sneakoscope/              mission state, policy, retention, logs, GX cartridges
+.codex/config.toml    Codex profiles used by Sneakoscope Codex
+.codex/hooks.json     hook entrypoints
+.agents/skills/       Sneakoscope Codex helper skills
+AGENTS.md             managed repository rules block
+```
+
+Storage is intentionally bounded:
+
+- process stdout/stderr are kept as bounded tails
+- large outputs are written to files
+- recursive scans have file/depth caps
+- `sks gc` compacts oversized JSONL logs and prunes old artifacts
+- `sks stats` reports package and `.sneakoscope` storage size
+
+See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for the detailed resource policy.
+
+## Visual Cartridges
+
+```bash
+sks gx init architecture-atlas
+```
+
+This creates:
+
+```text
+.sneakoscope/gx/cartridges/<name>/vgraph.json
+.sneakoscope/gx/cartridges/<name>/beta.json
+.sneakoscope/gx/cartridges/<name>/image-prompt.md
+```
+
+The intended flow is metadata first:
+
+```text
+vgraph.json
+  -> image-prompt.md
+  -> Codex $imagegen / GPT Image 2
+  -> sheet.png
+  -> vision parse.json
+  -> validate against vgraph.json
+```
+
+## 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.
+
+Default context layers:
+
+```text
+Q4 control bits
+Q3 tags
+Q2 fact cards when useful
+Q1 evidence snippets for verification
+Q0 raw logs only when necessary
+```
+
+## Package Layout
+
+```text
+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/hproof.mjs         done-gate evaluator
+src/core/init.mjs           project bootstrap and hook/skill installation
+src/core/retention.mjs      storage report and garbage collection policy
+src/core/triwiki-attention.mjs
+docs/PERFORMANCE.md         resource and leak policy
+crates/sks-core/         optional Rust helper source, not shipped in npm package
+```
+
+The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, and `LICENSE`; `.sneakoscope`, `.codex`, `.agents`, Rust sources, archives, and local state are excluded.
+
+## Development
+
+```bash
+npm run packcheck
+npm run selftest
+npm run doctor
+```
+
+`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/bin/sks.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/cli/main.mjs';
+
+main(process.argv.slice(2)).catch((err) => {
+  const message = err && err.stack ? err.stack : String(err);
+  console.error(message);
+  process.exitCode = 1;
+});

package/docs/PERFORMANCE.md

@@ -0,0 +1,39 @@
+# Sneakoscope Codex performance and leak policy
+
+Sneakoscope Codex v0.2 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.
+- `sks gc` runs after Ralph cycles by default.
+
+## 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.
+
+## Memory leaks
+
+- Child process stdout/stderr never accumulate unbounded strings.
+- Large outputs are written to log files and returned as tails.
+- Recursive file walking has file/depth caps.
+- No long-lived global caches are used.
+
+## Storage leaks
+
+- `.sneakoscope/policy.json` controls retention.
+- Old missions, old Ralph cycle directories, arenas, temp files, and oversized JSONL logs are removed or rotated by `sks gc`.
+- `sks stats` reports package/state size.
+
+## Rust decision
+
+Rust is useful for CPU-heavy long-running kernels, but not for the default npm package yet: native binaries increase package size and create OS/architecture install failure modes. Sneakoscope Codex therefore ships a zero-dependency Node runtime by default and includes an optional zero-dependency Rust helper source at `crates/sks-core` for future builds or users who want to compile locally.
+
+## Database safety resource policy
+
+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.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "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.",
+  "type": "module",
+  "bin": {
+    "sks": "bin/sks.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "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"
+  },
+  "keywords": [
+    "codex",
+    "sks",
+    "ai-agent",
+    "harness",
+    "ralph",
+    "llm-wiki",
+    "gpt-image-2",
+    "resource-safe",
+    "database-safe",
+    "supabase-mcp",
+    "bounded-memory",
+    "storage-safe",
+    "rust-optional",
+    "supabase",
+    "mcp-safety",
+    "db-guardian"
+  ],
+  "license": "MIT"
+}