sneakoscope 0.5.0 → 0.6.3

package/README.md

@@ -1,20 +1,233 @@
 <p align="center">
-  <img src="docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
+  <img src="https://raw.githubusercontent.com/mandarange/Sneakoscope-Codex/main/docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
 </p>
 
 <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.
+<p align="center">
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="npm version" src="https://img.shields.io/npm/v/sneakoscope.svg"></a>
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/sneakoscope.svg"></a>
+  <a href="https://github.com/mandarange/Sneakoscope-Codex"><img alt="GitHub stars" src="https://img.shields.io/github/stars/mandarange/Sneakoscope-Codex?style=flat"></a>
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="license" src="https://img.shields.io/npm/l/sneakoscope.svg"></a>
+  <img alt="node >=20.11" src="https://img.shields.io/badge/node-%3E%3D20.11-339933.svg">
+</p>
+
+Sneakoscope Codex is an update-aware, 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, Codex multi-agent Team orchestration, AutoResearch-style experiment loops, 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`.
+The npm package name is `sneakoscope`; the command is branded as SKS and exposed as lowercase `sks` for shell portability. The package also exposes a `sneakoscope` command alias, so `sks setup` and `sneakoscope setup` are equivalent.
+Global installation is the default and recommended setup. During `sks setup` or `sks init`, SKS resolves the global binary when possible and writes that absolute path into `.codex/hooks.json`, which avoids PATH issues in GUI or hook execution environments. For a project-only install, use `npm i -D sneakoscope` and initialize hooks with `npx sks setup --install-scope project`; this writes hook commands that call the local `node_modules/sneakoscope` binary.
 
 `@openai/codex` is intentionally not bundled. Install Codex separately, or set `SKS_CODEX_BIN` to the Codex executable you want Sneakoscope Codex to supervise.
 
+## One-Prompt LLM Install
+
+If you are using Codex App, ChatGPT, Claude Code, Cursor, or another coding agent, copy the whole block below into the agent from your target project directory. The agent should install SKS, initialize the project, verify the setup, and show the available commands in one pass.
+
+````text
+Install Sneakoscope Codex in the current project end to end. Do not ask follow-up questions unless a command requires user approval.
+
+Repository:
+https://github.com/mandarange/Sneakoscope-Codex.git
+
+Requirements:
+- Node.js must be >=20.11.
+- Codex CLI is installed separately. If it is missing, report that `@openai/codex` must be installed or `SKS_CODEX_BIN` must be set.
+- Use the published npm package for normal installs.
+- Do not modify application source files unless needed for SKS setup.
+
+Run:
+```bash
+npm i -g sneakoscope
+sks setup
+sks update-check
+sks doctor --fix
+sks selftest --mock
+sks commands
+sks dollar-commands
+```
+
+If npm reports `ENOTEMPTY`, `EEXIST`, or a broken old global package:
+```bash
+npm uninstall -g sneakoscope
+npm i -g sneakoscope
+sks setup
+sks doctor --fix
+```
+
+If `sks` is not on PATH:
+```bash
+npx -y -p sneakoscope sks setup
+npx -y -p sneakoscope sks doctor --fix
+npx -y -p sneakoscope sks selftest --mock
+npx -y -p sneakoscope sks commands
+npx -y -p sneakoscope sks dollar-commands
+```
+
+For project-only install:
+```bash
+npm i -D sneakoscope
+npx sks setup --install-scope project
+npx sks update-check
+npx sks doctor --fix --install-scope project
+npx sks selftest --mock
+npx sks commands
+npx sks dollar-commands
+```
+
+Finish by reporting pass/fail and explaining only these generated outputs:
+- `.sneakoscope/` mission state and policy
+- `.codex/config.toml` Codex App profiles
+- `.codex/hooks.json` SKS hook integration
+- `.codex/skills/` local Codex App skills
+- `.codex/agents/` local Codex App multi-agent roles
+- `.codex/SNEAKOSCOPE.md` Codex App quick reference
+- `AGENTS.md` repository rules
+
+Show command discovery:
+```bash
+sks help
+sks update-check
+sks commands
+sks usage team
+sks usage ralph
+sks quickstart
+sks codex-app
+sks dollar-commands
+```
+
+Tell the user they can use these prompt commands inside Codex App:
+```text
+$DF 글자 색 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$SKS show me available workflows
+$Team agree on the best plan and implement with specialists
+$Ralph implement this with mandatory clarification
+$Research investigate this idea
+$AutoResearch improve this workflow with experiments
+$DB check this migration safely
+```
+````
+
+## Repository
+
+```bash
+npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
+```
+
+Source repository: <https://github.com/mandarange/Sneakoscope-Codex.git>
+
+Use the registry install (`npm i -g sneakoscope`) for normal users. The GitHub install path is intended for testing an unreleased commit.
+
+Local development checkout:
+
+```bash
+git clone https://github.com/mandarange/Sneakoscope-Codex.git
+cd Sneakoscope-Codex
+npm i
+```
+
+## Installed Commands
+
+Installing the package exposes two equivalent shell commands:
+
+```bash
+sks <command>
+sneakoscope <command>
+```
+
+Use `sks --help` or `sneakoscope --help` to inspect the installed CLI. The user-facing subcommands are listed in [Commands](#commands).
+
+Useful discovery commands:
+
+```bash
+sks commands
+sks usage install
+sks usage ralph
+sks quickstart
+sks install-prompt
+sks codex-app
+sks dollar-commands
+sks df
+sks aliases
+```
+
+## Prompt Pipeline and $ Commands
+
+SKS installs a Codex App `UserPromptSubmit` hook that adds a lightweight prompt-optimization context to every user request. You do not need to type a command for basic routing: SKS will infer the lightest path before work starts.
+
+Use `$` prompt commands inside Codex App or another coding agent when you want to force a route:
+
+```text
+$DF        fast design/content fix
+$SKS       general Sneakoscope workflow/help
+$Team      multi-agent team orchestration
+$Ralph     clarification-gated Ralph mission
+$Research  frontier research mission
+$AutoResearch iterative experiment loop
+$DB        database/Supabase safety check
+$GX        deterministic visual context
+$Help      command and workflow help
+```
+
+`$DF` is intentionally small and fast. Use it for changes like text color, visible copy, labels, spacing, button text, or translation:
+
+```text
+$DF 글자 색 파란색으로 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$DF Change the CTA label to "Start"
+```
+
+DF should not start Ralph, Research, evaluation, or a broad redesign unless you explicitly ask for that.
+
+## Codex App
+
+Sneakoscope Codex can also be used from Codex App when the repository is opened in the app. Run setup once in the project:
+
+```bash
+sks setup
+```
+
+This creates the app-facing control surface:
+
+```text
+.codex/config.toml       Codex App profiles for SKS Ralph, research, and default work
+.codex/hooks.json        Codex App hook entrypoints routed through SKS guards
+.codex/skills/           local project skills for Ralph, DB safety, GX, research, and design work
+.codex/agents/           local Codex subagent roles for Team consensus, implementation, DB safety, and QA
+.codex/SNEAKOSCOPE.md    quick reference for using SKS inside Codex App
+AGENTS.md                repository rules loaded by Codex agents
+.sneakoscope/            mission state, gates, logs, policy, GX cartridges, and reports
+```
+
+Inside Codex App, you can ask the agent to use the local SKS control surface, for example:
+
+```text
+$DF 글자 색 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$Team agree on the plan, then implement it with a fresh specialist team.
+Use Sneakoscope Ralph mode to prepare this task.
+Run the latest Ralph mission with the sealed decision contract.
+Use SKS DB safety before touching database or Supabase files.
+Use SKS research mode for this investigation.
+```
+
+If Codex App cannot find `sks` from hooks, run:
+
+```bash
+sks fix-path
+```
+
+For a project-only install, use:
+
+```bash
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
+
 ## Requirements
 
 - Node.js `>=20.11`
@@ -25,8 +238,7 @@ Global installation is the default and recommended setup. For a project-only ins
 ## Quick Start
 
 ```bash
-sks doctor --fix
-sks init
+sks setup
 sks selftest --mock
 ```
 
@@ -34,8 +246,19 @@ Project-only setup:
 
 ```bash
 npm i -D sneakoscope
-npx sks doctor --fix --install-scope project
-npx sks init --install-scope project
+npx sks setup --install-scope project
+```
+
+If a GUI hook, Codex session, or another project cannot find `sks`, refresh the hook command with the resolved binary path:
+
+```bash
+sks fix-path
+```
+
+If your shell cannot find the global command yet, run through npm without relying on PATH:
+
+```bash
+npx -y -p sneakoscope sks setup
 ```
 
 Create a Ralph mission:
@@ -73,6 +296,12 @@ sks research run latest --max-cycles 3
 - **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.
+- **Prompt pipeline and `$` routes**: user prompts are lightly optimized by default, and Codex App users can force routes such as `$DF`, `$Team`, `$Ralph`, `$Research`, `$AutoResearch`, `$DB`, and `$GX`.
+- **Team orchestration**: `sks team` and `$Team` prepare a Codex multi-agent flow where planning agents debate options, the parent agent seals one objective, planning agents are closed, and a fresh implementation team handles disjoint work in parallel.
+- **AutoResearch loop**: open-ended improvement tasks use a small experiment cycle: program, hypothesis, experiment, metric, keep/discard, falsification, and honest conclusion.
+- **Update-aware hooks**: before work, SKS checks for a newer published package and asks whether to update now or skip for the current conversation only.
+- **Honest Mode finish**: final answers must include an evidence-aware verification pass before claiming the goal is complete.
+- **Fast DF mode**: `$DF` handles small design/content edits like color, copy, labels, spacing, and translation without unnecessary Ralph, Research, or evaluation loops.
 - **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.
@@ -80,6 +309,64 @@ sks research run latest --max-cycles 3
 - **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.
 
+## FAQ For Search And AI Answers
+
+### What is Sneakoscope Codex?
+
+Sneakoscope Codex is a Codex CLI harness for safer autonomous software work. It combines update checks, Codex App hooks, multi-agent Team orchestration, Ralph no-question execution, database safety guards, H-Proof completion gates, and bounded runtime state.
+
+### Does Sneakoscope Codex support Codex multi-agent teams?
+
+Yes. `sks setup` enables Codex `multi_agent`, creates `.codex/agents/*.toml` custom agents, and installs a `$Team` workflow for planning debate, consensus, fresh implementation workers, review, and final integration.
+
+### Does Sneakoscope Codex replace Codex CLI?
+
+No. `@openai/codex` is installed separately. Sneakoscope Codex supervises project workflow, hooks, safety policy, state, and local skills around Codex CLI and Codex App.
+
+### Why star the GitHub repository?
+
+Stars help developers discover a lightweight Codex workflow harness focused on database safety, multi-agent orchestration, update hygiene, honest completion checks, and practical autonomous coding loops.
+
+## Team Workflow
+
+Team mode uses Codex subagents/custom agents as an orchestration protocol rather than a single long-running worker. `sks setup` enables `multi_agent`, sets agent concurrency limits, and installs local agent role files under `.codex/agents/`.
+
+```text
+team planning
+  -> spawn read-only/explorer specialists for code paths, risks, DB safety, tests, and options
+  -> synthesize one agreed objective with constraints and acceptance criteria
+  -> close planning agents
+
+fresh implementation team
+  -> assign disjoint write scopes to implementation workers
+  -> run work in parallel only when ownership does not overlap
+  -> review with QA and DB safety specialists
+  -> parent orchestrator integrates, verifies, and reports evidence
+```
+
+Create a Team mission:
+
+```bash
+sks team "implement this feature safely"
+```
+
+Inside Codex App, use:
+
+```text
+$Team agree on the best plan, then implement with specialists
+```
+
+The generated Team artifacts are:
+
+```text
+.sneakoscope/missions/<MISSION_ID>/team-plan.json
+.sneakoscope/missions/<MISSION_ID>/team-workflow.md
+.codex/agents/team-consensus.toml
+.codex/agents/implementation-worker.toml
+.codex/agents/db-safety-reviewer.toml
+.codex/agents/qa-reviewer.toml
+```
+
 ## Ralph Workflow
 
 ```text
@@ -110,7 +397,32 @@ Core invariants:
 
 ## Commands
 
+There are two command surfaces:
+
+- **Terminal CLI commands**: run in a shell as `sks ...` or `sneakoscope ...`.
+- **Prompt `$` commands**: type inside Codex App or another coding agent prompt, not in a shell.
+
+All terminal examples below use `sks`, but the same commands can be run with the `sneakoscope` alias.
+
+### Terminal CLI
+
 ```bash
+sks help [topic]
+sks update-check [--json]
+sks commands [--json]
+sks usage [install|setup|team|ralph|research|db|codex-app|df|dollar|eval|gx]
+sks quickstart
+sks install-prompt [--project]
+sks codex-app
+sks dollar-commands [--json]
+sks df
+sks aliases
+
+sks --help
+sneakoscope --help
+
+sks setup [--install-scope global|project] [--force] [--json]
+sks fix-path [--install-scope global|project] [--json]
 sks doctor [--fix] [--json] [--install-scope global|project]
 sks init [--force] [--install-scope global|project]
 sks selftest [--mock]
@@ -138,6 +450,7 @@ sks eval compare --baseline old.json --candidate new.json [--json]
 sks eval thresholds
 
 sks hproof check [mission-id|latest]
+sks team "task" [--json]
 sks gx init [name]
 sks gx render [name] [--format svg|html|all]
 sks gx validate [name]
@@ -146,11 +459,51 @@ sks gx snapshot [name]
 sks profile show
 sks profile set <model>
 sks gc [--dry-run] [--json]
+sks memory [--dry-run] [--json]
 sks stats [--json]
 ```
 
 `sks memory` is currently an alias for garbage collection/retention handling.
 
+### Prompt $ Commands
+
+Use these by typing them at the start of a prompt in Codex App or another coding agent:
+
+```text
+$DF <small design/content request>
+$SKS <general Sneakoscope request>
+$Team <multi-agent team request>
+$Ralph <clarification-gated mission request>
+$Research <research/discovery request>
+$AutoResearch <iterative experiment request>
+$DB <database or Supabase safety request>
+$GX <visual context request>
+$Help <command/help request>
+```
+
+Examples:
+
+```text
+$DF 글자 색 파란색으로 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$DF Change the CTA label to "Start"
+$Ralph 결제 실패 재시도 로직 개선
+$Research LLM 에이전트 평가 방법론 조사
+$DB 이 migration 안전한지 검사해줘
+$GX 현재 아키텍처를 시각 컨텍스트로 만들어줘
+$Help 사용 가능한 명령어 알려줘
+```
+
+`$DF` is the fast path for simple design/content edits. It is intentionally scoped to the requested change and should not run Ralph, Research, eval, or broad redesign loops unless you explicitly ask.
+
+To inspect these routes from the terminal:
+
+```bash
+sks dollar-commands
+sks df
+sks usage dollar
+```
+
 ## 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:
@@ -272,6 +625,9 @@ sks hproof check latest
 .sneakoscope/              mission state, policy, retention, logs, GX cartridges
 .codex/config.toml    Codex profiles used by Sneakoscope Codex
 .codex/hooks.json     hook entrypoints
+.codex/skills/        Codex App local project skills
+.codex/agents/        Codex App custom agents for Team mode
+.codex/SNEAKOSCOPE.md Codex App quick reference
 .agents/skills/       Sneakoscope Codex helper skills
 AGENTS.md             managed repository rules block
 ```
@@ -279,7 +635,7 @@ AGENTS.md             managed repository rules block
 Install scope controls `.codex/hooks.json`:
 
 ```text
-global  -> sks hook ...
+global  -> /absolute/path/to/sks hook ... when resolvable, otherwise sks hook ...
 project -> node ./node_modules/sneakoscope/bin/sks.mjs hook ...
 ```
 
@@ -362,12 +718,33 @@ The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, a
 ## Development
 
 ```bash
+npm run repo-audit
 npm run packcheck
 npm run selftest
 npm run sizecheck
+npm run release:check
 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 repo-audit` checks tracked files for risky local paths and high-confidence secret material such as private keys, npm/GitHub/OpenAI-style tokens, local MCP configs, DB dumps, and credential files. It is included in `release:check` and `prepublishOnly`. The package intentionally does not define `prepack`; GitHub installs should not trigger npm's heavier git-dependency preparation path for normal users.
+
+`npm run sizecheck` blocks accidental package bloat during `release:check`, `publish:dry`, and `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.
+
+## Publishing
+
+The npm package is published as public package `sneakoscope`. You must be logged in as an npm owner for that package before publishing.
+
+```bash
+npm whoami
+npm owner ls sneakoscope
+npm run publish:dry
+npm run publish:npm
+```
+
+If `npm whoami` returns `E401 Unauthorized`, run `npm login` with an owner account or ask an existing owner to add your npm username:
+
+```bash
+npm owner add <your-npm-username> sneakoscope
+```

package/docs/PERFORMANCE.md

@@ -1,6 +1,6 @@
 # Sneakoscope Codex performance and leak policy
 
-Sneakoscope Codex v0.5 is designed to keep runtime, package size, RAM, and storage bounded.
+Sneakoscope Codex v0.6 is designed to keep runtime, package size, RAM, and storage bounded.
 
 ## Speed
 
@@ -36,7 +36,7 @@ The accuracy metric is not a live model task score. It is a deterministic proxy
 - `@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.
+- `npm run sizecheck` enforces package limits during `release:check`, `publish:dry`, and publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
 
 ## Memory leaks
 

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "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.",
+  "version": "0.6.3",
+  "description": "Sneakoscope Codex: update-aware, database-safe Codex CLI harness with multi-agent Team orchestration, Ralph no-question execution, autoresearch-style loops, and H-Proof gates.",
   "type": "module",
+  "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mandarange/Sneakoscope-Codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mandarange/Sneakoscope-Codex/issues"
+  },
   "bin": {
-    "sks": "bin/sks.mjs"
+    "sks": "bin/sks.mjs",
+    "sneakoscope": "bin/sks.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "files": [
     "bin",
@@ -18,12 +31,15 @@
     "node": ">=20.11"
   },
   "scripts": {
+    "repo-audit": "node ./scripts/repo-audit.mjs",
     "selftest": "node ./bin/sks.mjs selftest --mock",
     "doctor": "node ./bin/sks.mjs doctor",
     "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"
+    "release:check": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck",
+    "publish:dry": "npm run release:check && npm --cache /tmp/sks-npm-cache pack --dry-run",
+    "publish:npm": "npm --cache /tmp/sks-npm-cache publish --access public",
+    "prepublishOnly": "npm run release:check"
   },
   "keywords": [
     "sneakoscope",
@@ -31,9 +47,19 @@
     "sks",
     "cli",
     "ai-agent",
+    "ai-agents",
     "harness",
+    "codex-cli",
+    "codex-app",
+    "multi-agent",
+    "subagents",
+    "agent-orchestration",
+    "agent-team",
     "ralph",
     "research",
+    "autoresearch",
+    "honest-mode",
+    "update-check",
     "hypothesis",
     "discovery",
     "llm-wiki",