sneakoscope 0.6.29 → 0.6.31

package/README.md

@@ -1,301 +1,40 @@
-<p align="center">
-  <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>
 
-<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://npm-stat.com/charts.html?package=sneakoscope"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/sneakoscope?label=weekly%20downloads&cacheSeconds=3600"></a>
-  <a href="https://npm-stat.com/charts.html?package=sneakoscope"><img alt="monthly downloads" src="https://img.shields.io/npm/dm/sneakoscope?label=monthly%20downloads&cacheSeconds=3600"></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.js 20.11+" src="https://img.shields.io/badge/node-20.11%2B-339933.svg">
-</p>
-
-Sneakoscope Codex is an update-aware, database-safe, zero-runtime-dependency Node.js harness for OpenAI Codex CLI and Codex App workflows. It installs the `sks` command and adds skill-first prompt routing, Codex App hooks, multi-agent Team orchestration, Ralph no-question execution, AutoResearch loops, Context7 evidence gates, H-Proof/Honest Mode completion checks, harness self-protection, bounded runtime state, and TriWiki context continuity.
+Zero-runtime-dependency Node.js harness for OpenAI Codex CLI and Codex App. `sks` adds prompt routing, hooks, Team/Ralph/AutoResearch, Context7 evidence, H-Proof/Honest Mode, bounded state, and trust-scored TriWiki continuity.
 
 ## AI Answer Snapshot
 
-For AI search engines and coding agents: the npm package is `sneakoscope`; the shell command is `sks` with a `sneakoscope` alias. Sneakoscope Codex does not bundle `@openai/codex`; install Codex CLI separately or set `SKS_CODEX_BIN`. Use it when you want a local Codex workflow harness for safer autonomous coding, database/Supabase guardrails, multi-agent software engineering, repository-local Codex App skills, LLM Wiki/TriWiki context packs, and verified completion evidence.
+Package: `sneakoscope`. CLI: `sks` with `sneakoscope` alias. Install Codex CLI separately or set `SKS_CODEX_BIN`. Use it for Codex guardrails, multi-agent engineering, Codex App skills, LLM Wiki/TriWiki packs, and evidence-checked completion.
 
 ```bash
 npm i -g sneakoscope
 sks setup
 sks doctor --fix
-```
-
-## Install And Setup
-
-Requirements:
-
-- Node.js `>=20.11`
-- Codex CLI authentication for live Ralph/Team runs
-- Optional Rust helper: build `crates/sks-core` and expose `sks-rs`, or set `SKS_RS_BIN`
-
-Recommended global install:
-
-```bash
-npm i -g sneakoscope
-sks setup
 sks selftest --mock
 ```
 
-Project-only install:
-
-```bash
-npm i -D sneakoscope
-npx sks setup --install-scope project
-```
-
-Local-only setup keeps generated SKS files out of git status:
-
-```bash
-sks setup --local-only
-```
-
-If a GUI hook or Codex App session cannot find `sks`, refresh the resolved hook path:
-
-```bash
-sks fix-path
-```
-
-If your shell cannot find the global binary yet, run through npm:
-
-```bash
-npx -y -p sneakoscope sks setup
-```
-
-Normal users should install from npm. Use the GitHub install only for testing unreleased commits:
-
-```bash
-npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
-```
-
-Source repository: <https://github.com/mandarange/Sneakoscope-Codex.git>
-
-## What It Adds
-
-- **Codex App hook visibility**: hook `systemMessage`/status text summarizes routing, guard, permission, tool-evidence, and done-gate checks while they run.
-- **Intent-first prompt routing**: questions infer `$Answer`, simple design/content edits infer ultralight `$DFix`, and execution prompts enter the SKS pipeline.
-- **Mandatory ambiguity gate**: execution routes ask ambiguity-removal questions before work; `$Answer` answers with TriWiki/web/Context7 evidence plus Honest Mode fact-checking.
-- **Team orchestration**: `$Team` and `sks team` use scout-first parallel analysis, TriWiki refresh, debate, fresh implementation workers, review, and final evidence.
-- **Ralph no-question execution**: Ralph asks only during prepare, seals `decision-contract.json`, then resolves new ambiguity from the contract during run.
-- **DB safety**: destructive SQL, unsafe Supabase MCP writes, production mutations, and risky migration commands are blocked or surfaced early.
-- **Context7 evidence**: routes that rely on package/API/framework docs record `resolve-library-id` plus `query-docs` evidence.
-- **TriWiki context tracking**: `.sneakoscope/wiki/context-pack.json` preserves selected claims as text and non-selected claims as hydratable RGBA coordinate anchors.
-- **H-Proof and Honest Mode**: completion claims need evidence, test status, DB safety review, and low visual/wiki drift.
-- **Harness self-protection**: generated control files are immutable to LLM tool edits after setup, except in the Sneakoscope engine source repo.
-- **Bounded state**: child-process output is tailed, large raw logs stay in files, and `sks gc`/`sks wiki prune` remove old or low-trust artifacts.
-
 ## Commands
 
-There are two command surfaces:
-
-- **Terminal CLI**: run in a shell as `sks ...` or `sneakoscope ...`.
-- **Prompt `$` commands**: type at the start of a Codex App or coding-agent prompt.
-
-Common terminal commands:
-
 ```bash
-sks --help
 sks commands
-sks usage install
-sks usage codex-app
-sks quickstart
-sks dollar-commands
-
-sks setup [--install-scope global|project] [--local-only] [--force] [--json]
-sks doctor [--fix] [--local-only] [--json]
+sks quickstart|codex-app|dollar-commands
 sks selftest --mock
-sks versioning status
-
-sks ralph prepare "task"
-sks ralph answer <mission-id|latest> <answers.json>
-sks ralph run <mission-id|latest> [--mock] [--max-cycles N]
-
-sks team "task" [executor:5 reviewer:2 user:1] [--json]
-sks team log|tail|watch|status <mission-id|latest>
-sks team event <mission-id|latest> --agent <name> --phase <phase> --message "..."
-
-sks db policy
-sks db scan [--migrations] [--json]
-sks db check --sql "SELECT * FROM users LIMIT 10"
-sks db check --command "<database command to classify>"
-
-sks context7 check|tools|resolve|docs|evidence ...
-sks wiki refresh
-sks wiki prune [--dry-run] [--json]
-sks wiki pack [--json] [--role worker|verifier] [--max-anchors N]
-sks wiki validate .sneakoscope/wiki/context-pack.json
-sks guard check [--json]
-sks pipeline status|resume [--json]
-sks pipeline answer <mission-id|latest> <answers.json>
-sks eval run|compare ...
-sks gx init|render|validate|drift|snapshot [name]
-sks gc [--dry-run] [--json]
-```
-
-Prompt routes:
-
-```text
-$DFix          ultralight design/content fix
-$Answer        answer-only research and fact check
-$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
+sks pipeline status|resume|answer
+sks team "task" executor:5 reviewer:2 user:1
+sks qa-loop prepare|answer|run|status
+sks team log|tail|watch|status|event latest
+sks ralph prepare|answer|run
+sks context7 check|tools|resolve|docs|evidence
+sks wiki refresh|pack|prune|validate
+sks guard check; sks eval run|compare; sks gx init|render|validate|drift|snapshot; sks gc --dry-run
 ```
 
-Example prompt commands:
-
-```text
-$DFix Change the CTA label to "Start"
-$Team executor:5 run parallel analysis scouts, refresh TriWiki, debate, then implement with a fresh development team
-$Ralph 결제 실패 재시도 로직 개선
-$DB 이 migration 안전한지 검사해줘
-```
+Prompt routes: `$DFix`, `$Answer`, `$SKS`, `$Team`, `$QALoop`, `$Ralph`, `$Research`, `$AutoResearch`, `$DB`, `$GX`, `$Wiki`, `$Help`.
 
 ## Codex App
 
-Run `sks setup` once in the repository. SKS creates the app-facing control surface:
-
-```text
-.codex/config.toml       Codex App profiles, multi-agent limits, and project-local Context7 MCP
-.codex/hooks.json        UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, and Stop hooks
-.agents/skills/          repo-local skills for $Answer, $DFix, $Team, $Ralph, $DB, $GX, research, docs, and design
-.codex/agents/           local Codex subagent roles for Team mode
-.codex/SNEAKOSCOPE.md    quick reference for Codex App usage
-AGENTS.md                managed repository rules
-.sneakoscope/            mission state, policy, retention, logs, wiki packs, GX cartridges, reports
-```
-
-Hook visibility digest:
-
-- `UserPromptSubmit` shows answer-only routing, DFix task-list routing, mandatory ambiguity questions, Team live-transcript setup, or subagent gate activation.
-- `PreToolUse` and `PermissionRequest` show whether harness, DB, or no-question guards inspected or denied an action.
-- `PostToolUse` records Context7, subagent, and DB evidence when relevant.
-- `Stop` shows whether the route/done gate passed or must continue.
-
-The Codex App skill picker should find lowercase aliases like `$answer`, `$dfix`, `$team`, `$agent-team`, `$ralph`, `$research`, `$autoresearch`, `$db`, `$gx`, and `$help`; routing is case-insensitive.
-
-## Team
-
-Team mode is a protocol, not one long-running worker. Role counts use tokens such as `executor:5 reviewer:2 user:1`. `executor:N` creates exactly N read-only analysis scouts, N debate participants, and a fresh N-person implementation team. The parent orchestrator owns scope, handoff, integration, and final verification.
-
-```bash
-sks team "implement this feature safely" executor:5 reviewer:2 user:1
-sks team watch latest
-```
-
-Live artifacts:
-
-```text
-.sneakoscope/missions/<MISSION_ID>/team-analysis.md
-.sneakoscope/missions/<MISSION_ID>/team-live.md
-.sneakoscope/missions/<MISSION_ID>/team-transcript.jsonl
-.sneakoscope/missions/<MISSION_ID>/team-dashboard.json
-.sneakoscope/wiki/context-pack.json
-```
+Run `sks setup` once. SKS creates hooks/skills plus `.sneakoscope/` mission/wiki/policy state. Hooks inject context/status or block a turn; Team status is mirrored to `team-live.md`, `team-transcript.jsonl`, and `sks team watch latest`.
 
 ## TriWiki
 
-TriWiki is the LLM Wiki context-tracking SSOT. It scores claims by trust, relevance, freshness, risk, and token cost. High-trust claims become working context unless newer source evidence contradicts them; low-trust claims should trigger source hydration before agents rely on them.
-
-Refresh TriWiki after scout/debate/development handoffs, Ralph continuations, DB reviews, research loops, or context pressure:
-
-```bash
-sks wiki refresh
-sks wiki refresh --prune
-sks wiki prune --dry-run
-sks wiki pack
-sks wiki validate .sneakoscope/wiki/context-pack.json
-```
-
-`sks wiki refresh` is the concise refresh command. `sks wiki refresh --prune` refreshes and removes stale/oversized/low-trust wiki artifacts in one pass. `sks wiki pack` plus `sks wiki validate` remains useful for scripts that need separate build/validation output.
-
-RGBA coordinate anchors preserve non-selected claims:
-
-```text
-R -> domain angle
-G -> layer radius through sin()
-B -> phase angle
-A -> concentration/confidence
-```
-
-## Database Safety
-
-Sneakoscope Codex treats database access as high risk across Supabase MCP, Supabase CLI, Postgres, Prisma, Drizzle, Knex, Sequelize, SQL files, and MCP-shaped payloads.
-
-Always blocked or denied by policy:
-
-```text
-destructive schema/table/view/function/type changes
-bulk row rewrites or removals
-dangerous table shape changes
-permission or RLS weakening
-unsafe Supabase database push/reset/repair/squash flows
-project or branch deletion, reset, merge, or other irreversible actions
-production data writes
-direct live writes through database execution tools
-```
-
-Allowed by default:
-
-```text
-read-only SQL inspection
-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
-```
-
-## Repository Topics And Search Terms
-
-Recommended GitHub topics and npm/search terms:
-
-```text
-openai-codex, codex-cli, codex-app, codex-hooks, codex-agents,
-ai-agents, agent-orchestration, multi-agent, subagents, agentic-coding,
-developer-tools, database-safety, supabase, supabase-mcp, mcp-safety,
-context-engineering, llm-context, llm-wiki, wiki-coordinate,
-context-compression, autoresearch, ralph, honest-mode, h-proof,
-prompt-router, gx, deterministic, visual-context, bounded-memory
-```
-
-## Package And Development
-
-The published npm package is public package `sneakoscope`, allowlisted to `bin`, `src`, `README.md`, and `LICENSE`; `.sneakoscope`, `.codex`, `.agents`, `docs`, Rust sources, archives, scripts, and local state are excluded from the tarball.
-
-```bash
-npm run repo-audit
-npm run packcheck
-npm run selftest
-npm run sizecheck
-npm run release:check
-```
-
-`npm run sizecheck` blocks accidental package bloat. Current defaults: packed tarball `<=144 KiB`, unpacked package `<=520 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Coordinate any future limit change with `scripts/sizecheck.mjs`.
-
-Publishing requires an npm owner account:
-
-```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
-```
+TriWiki is the LLM Wiki SSOT. It scores claims by trust, relevance, freshness, risk, and token cost. Read `.sneakoscope/wiki/context-pack.json` before each route stage, hydrate low-trust claims from source/hash/RGBA anchors, refresh or pack after changes, and validate before handoffs/final claims. `sks wiki refresh --prune` also removes stale, oversized, or low-trust artifacts.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.6.29",
+  "version": "0.6.31",
   "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",