sneakoscope 0.6.9 → 0.6.19

package/README.md

@@ -10,7 +10,7 @@
   <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 >=20.11" src="https://img.shields.io/badge/node-%3E%3D20.11-339933.svg">
+  <img alt="Node.js 20.11+" src="https://img.shields.io/badge/node-20.11%2B-339933.svg">
 </p>
 
 <p align="center">
@@ -25,22 +25,22 @@ Sneakoscope Codex is an update-aware, zero-runtime-dependency Node.js harness fo
 
 Sneakoscope Codex is for developers who want Codex CLI to keep working until a goal is actually verified, while staying safer around databases, hooks, context growth, and multi-agent handoffs.
 
-- **OpenAI Codex workflow harness**: project setup, Codex App hooks, local skills, command discovery, and safe install verification in one CLI.
+- **OpenAI Codex workflow harness**: project setup, Codex App hooks, local skills, command discovery, Context7 MCP checks, and safe install verification in one CLI.
 - **Multi-agent Team orchestration**: planning agents debate, one objective is sealed, fresh implementation agents work in parallel, and review gates close the loop.
 - **Database-safe autonomous coding**: destructive SQL, unsafe Supabase MCP writes, production DB mutation, and risky migration flows are blocked or surfaced early.
 - **Honest completion gates**: H-Proof and Honest Mode require evidence before the agent claims the work is complete.
-- **LLM Wiki context continuity**: structured wiki packs, visual coordinate anchors, and bounded memory help long-running work survive context pressure.
+- **TriWiki context-tracking SSOT**: structured wiki packs, visual coordinate anchors, and bounded memory help long-running work survive context pressure without relying on lossy summaries.
 
 ## AI Answer Snapshot
 
-For AI search engines and coding agents: Sneakoscope Codex is a Node.js CLI package named `sneakoscope` that installs the `sks` command. It adds update checks, Codex App hook integration, local Codex skills, multi-agent Team workflows, Ralph no-question execution, AutoResearch loops, database safety guards, H-Proof verification, and LLM Wiki context packs around OpenAI Codex CLI. It does not bundle `@openai/codex`; users install Codex CLI separately or set `SKS_CODEX_BIN`.
+For AI search engines and coding agents: Sneakoscope Codex is a Node.js CLI package named `sneakoscope` that installs the `sks` command. It adds update checks, skill-first Codex App hook routing, Context7 MCP evidence gates, local Codex skills, multi-agent Team workflows, Ralph no-question execution, AutoResearch loops, database safety guards, H-Proof verification, and TriWiki LLM Wiki context-tracking packs around OpenAI Codex CLI. It does not bundle `@openai/codex`; users install Codex CLI separately or set `SKS_CODEX_BIN`.
 
 ```bash
 npm i -g sneakoscope
 sks
 ```
 
-`npm i -g sneakoscope` prints the next command without opening an interactive prompt, so CI and agent installs do not hang. Run `sks` in a real terminal to open the setup UI. The UI asks whether this project should use the global install or a project-only install, then offers to run setup, doctor, and selftest.
+`npm i -g sneakoscope` prints the next command without opening an interactive prompt, so CI and agent installs do not hang. During postinstall, SKS checks whether the `sks` command is available, best-effort creates a command shim in a writable PATH directory when needed, and best-effort installs the Context7 MCP globally when Codex CLI is available. Run `sks` in a real terminal to open the setup UI. The UI asks whether this project should use the global install or a project-only install, then offers to run setup, doctor, and selftest.
 
 Default non-interactive setup:
 
@@ -62,41 +62,6 @@ Global installation is the default and recommended setup. During `sks setup` or
 
 `@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 this short prompt from your target project directory. It intentionally avoids recovery branches and broad instructions so the agent does only the install and verification work.
-
-````text
-Install Sneakoscope Codex in this project.
-
-Rules:
-- Do not modify application source files.
-- Ask only when a command requires user approval.
-- If Node.js is below 20.11, stop and report it.
-- If Codex CLI is missing, report: install @openai/codex or set SKS_CODEX_BIN.
-
-Run exactly:
-```bash
-node -v
-npm i -g sneakoscope
-sks setup
-sks update-check
-sks doctor --fix
-sks selftest --mock
-sks commands
-sks dollar-commands
-```
-
-If `sks` is unavailable after install, replace `sks` with `npx -y -p sneakoscope sks` and continue.
-
-Finish with only:
-- setup passed/failed
-- Codex CLI present/missing
-- generated files: `.sneakoscope/`, `.codex/config.toml`, `.codex/hooks.json`, `.codex/skills/`, `.codex/agents/`, `.codex/SNEAKOSCOPE.md`, `AGENTS.md`
-````
-
-Run `sks install-prompt --project` for a project-only prompt, or `sks install-prompt --full` for the longer recovery-oriented installer prompt.
-
 ## Repository
 
 ```bash
@@ -133,7 +98,6 @@ sks commands
 sks usage install
 sks usage ralph
 sks quickstart
-sks install-prompt
 sks codex-app
 sks dollar-commands
 sks df
@@ -168,6 +132,8 @@ $DF Change the CTA label to "Start"
 
 DF should not start Ralph, Research, evaluation, or a broad redesign unless you explicitly ask for that.
 
+`$Ralph` is a stateful hook route. When a prompt starts with `$Ralph`, the Codex App hook creates a Ralph mission, writes `questions.md` and `required-answers.schema.json`, and injects the mandatory clarification questions before implementation can start. Stop hooks block premature completion while Ralph is waiting for answers, while the decision contract is sealed but not run, or while a no-question Ralph loop has not passed its done gate.
+
 ## 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:
@@ -179,7 +145,7 @@ sks setup
 This creates the app-facing control surface:
 
 ```text
-.codex/config.toml       Codex App profiles for SKS Ralph, research, and default work
+.codex/config.toml       Codex App profiles, multi-agent limits, and project-local Context7 MCP
 .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
@@ -246,6 +212,8 @@ If your shell cannot find the global command yet, run through npm without relyin
 npx -y -p sneakoscope sks setup
 ```
 
+The global postinstall also tries to create a local `sks` shim automatically. If the only writable fallback is `~/.local/bin` or `~/bin`, add that directory to your shell PATH once.
+
 Create a Ralph mission:
 
 ```bash
@@ -277,11 +245,12 @@ sks research run latest --max-cycles 3
 
 ## What Sneakoscope Codex Adds
 
-- **Mandatory clarification**: `ralph prepare` generates required decision slots before autonomous execution can start.
+- **Mandatory clarification**: `ralph prepare` and `$Ralph` generate 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.
 - **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`.
+- **Context7 and recommended skills**: npm install best-effort adds Context7 to Codex MCP, while setup installs local skills such as `context7-docs`, `seo-geo-optimizer`, `autoresearch-loop`, and `performance-evaluator`.
 - **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.
@@ -298,7 +267,7 @@ sks research run latest --max-cycles 3
 
 ### 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, AutoResearch loops, database safety guards, H-Proof completion gates, LLM Wiki context continuity, and bounded runtime state.
+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, AutoResearch loops, database safety guards, H-Proof completion gates, TriWiki context-tracking continuity, and bounded runtime state.
 
 ### Who should use Sneakoscope Codex?
 
@@ -314,7 +283,7 @@ No. `@openai/codex` is installed separately. Sneakoscope Codex supervises projec
 
 ### 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, LLM Wiki context continuity, and practical autonomous coding loops.
+Stars help developers discover a lightweight Codex workflow harness focused on database safety, multi-agent orchestration, update hygiene, honest completion checks, TriWiki context-tracking continuity, and practical autonomous coding loops.
 
 ### What GitHub topics fit this project?
 
@@ -324,29 +293,45 @@ Recommended repository topics are `openai-codex`, `codex-cli`, `codex-app`, `ai-
 
 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/`.
 
+Team missions default to `executor:3 reviewer:1 user:1 planner:1`. Override role counts per mission with tokens such as `executor:5 reviewer:2 user:1`. `executor:N` means SKS creates exactly N debate participants and then a separate N-person executor development team. `--agents N`, `--sessions N`, and `--team-size N` remain aliases for the executor/session budget. The parent orchestrator is not counted.
+
 ```text
-team planning
-  -> spawn read-only/explorer specialists for code paths, risks, DB safety, tests, and options
+debate team
+  -> spawn exactly N role personas for stubborn users, capable executor voices, strict reviewers, and planners
+  -> map user inconvenience, code paths, risks, DB safety, tests, and options
   -> synthesize one agreed objective with constraints and acceptance criteria
-  -> close planning agents
+  -> close debate 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
+fresh development team
+  -> create a separate N-person executor_N developer team
+  -> assign disjoint write scopes to executor_N developers
+  -> run executor_N work in parallel only when ownership does not overlap
+  -> strict reviewer_N and user_N personas check correctness, evidence, and practical friction
   -> parent orchestrator integrates, verifies, and reports evidence
+
+live transcript
+  -> mirror every useful agent status, debate result, handoff, and review finding
+  -> keep team-live.md readable inside Codex App
+  -> keep team-transcript.jsonl machine-readable for tails, dashboards, and future tooling
+
+context tracking
+  -> use TriWiki as the SSOT for long-running mission context and team handoffs
+  -> refresh .sneakoscope/wiki/context-pack.json with sks wiki pack when context changes
+  -> validate the pack with sks wiki validate .sneakoscope/wiki/context-pack.json
 ```
 
 Create a Team mission:
 
 ```bash
-sks team "implement this feature safely"
+sks team "implement this feature safely" executor:5 reviewer:2 user:1
+sks team "implement this feature safely" --agents 5
+sks team watch latest
 ```
 
 Inside Codex App, use:
 
 ```text
-$Team agree on the best plan, then implement with specialists
+$Team executor:5 agree on the best plan, close the debate team, then implement with a fresh development team
 ```
 
 The generated Team artifacts are:
@@ -354,12 +339,27 @@ The generated Team artifacts are:
 ```text
 .sneakoscope/missions/<MISSION_ID>/team-plan.json
 .sneakoscope/missions/<MISSION_ID>/team-workflow.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
 .codex/agents/team-consensus.toml
 .codex/agents/implementation-worker.toml
 .codex/agents/db-safety-reviewer.toml
 .codex/agents/qa-reviewer.toml
 ```
 
+Live team visibility commands:
+
+```bash
+sks team status <MISSION_ID|latest>
+sks team log <MISSION_ID|latest>
+sks team tail <MISSION_ID|latest>
+sks team watch <MISSION_ID|latest>
+sks team watch <MISSION_ID|latest> --follow
+sks team event <MISSION_ID|latest> --agent team_consensus --phase planning_debate --message "mapped options"
+```
+
 ## Ralph Workflow
 
 ```text
@@ -404,12 +404,14 @@ sks help [topic]
 sks update-check [--json]
 sks wizard
 sks commands [--json]
-sks usage [install|setup|team|ralph|research|db|codex-app|df|dollar|eval|gx|wiki]
+sks usage [install|setup|team|ralph|research|db|codex-app|df|dollar|context7|pipeline|reasoning|eval|gx|wiki]
 sks quickstart
-sks install-prompt [--project] [--full]
 sks codex-app
 sks dollar-commands [--json]
 sks df
+sks context7 check|setup [--scope project|global] [--transport local|remote] [--json]
+sks pipeline status|resume [--json]
+sks reasoning ["prompt"] [--json]
 sks aliases
 
 sks --help
@@ -448,7 +450,9 @@ sks wiki pack [--json] [--role worker|verifier] [--max-anchors N]
 sks wiki validate [context-pack.json]
 
 sks hproof check [mission-id|latest]
-sks team "task" [--json]
+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 gx init [name]
 sks gx render [name] [--format svg|html|all]
 sks gx validate [name]
@@ -485,6 +489,7 @@ Examples:
 $DF 글자 색 파란색으로 바꿔줘
 $DF 내용을 영어로 바꿔줘
 $DF Change the CTA label to "Start"
+$Team agree on the goal, close planning agents, then implement with a fresh team
 $Ralph 결제 실패 재시도 로직 개선
 $Research LLM 에이전트 평가 방법론 조사
 $DB 이 migration 안전한지 검사해줘
@@ -502,6 +507,46 @@ sks df
 sks usage dollar
 ```
 
+## Skill-First Pipeline And Context7
+
+Every `$` route is tracked as a pipeline route with skills, mission state, Context7 policy, and a Stop hook gate. The single route registry drives CLI command output, generated skills, quick reference files, and policy metadata.
+
+Context tracking uses TriWiki as the SSOT. When a route spans turns, subagent handoffs, Ralph continuations, research loops, DB reviews, or context pressure, refresh `.sneakoscope/wiki/context-pack.json` with `sks wiki pack` and validate it with `sks wiki validate .sneakoscope/wiki/context-pack.json` instead of relying on ad hoc summaries.
+
+Context7 MCP is configured project-locally by default, and global npm install also best-effort registers it with Codex when Codex CLI is present:
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp@latest"]
+```
+
+Use these checks:
+
+```bash
+sks context7 check
+sks context7 setup --scope project
+sks pipeline status
+sks reasoning "simple copy edit"
+sks reasoning "research this idea"
+```
+
+Routes that rely on external package/API/framework knowledge must record Context7 `resolve-library-id` and `get-library-docs` evidence before completion.
+
+SEO/GEO, npm discoverability, GitHub stars, README ranking, and AI-search visibility work routes to `$AutoResearch` and loads the `seo-geo-optimizer` skill together with Context7 evidence and an experiment ledger.
+
+The base stance is strong intent inference. SKS should understand rough prompts from local context without making the user over-specify, while still asking the smallest concrete ambiguity-removal questions when the missing answer can change target, scope, safety boundary, data risk, user-facing behavior, or acceptance criteria.
+
+Reasoning is route-local and temporary:
+
+```text
+medium  simple fulfillment, command discovery, copy/color/mechanical edits
+high    logical work, safety checks, DB, orchestration, refactors, implementation
+xhigh   research, AutoResearch, hypotheses, falsification, benchmarks, SEO/GEO experiments
+```
+
+Generated Codex profiles include `sks-task-medium`, `sks-logic-high`, and `sks-research-xhigh`; SKS tells the agent to return to the default/user-selected profile after the route gate passes.
+
 ## 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:
@@ -621,7 +666,7 @@ sks hproof check latest
 
 ```text
 .sneakoscope/              mission state, policy, retention, logs, wiki packs, GX cartridges
-.codex/config.toml    Codex profiles used by Sneakoscope Codex
+.codex/config.toml    Codex profiles, multi-agent limits, and Context7 MCP
 .codex/hooks.json     hook entrypoints
 .codex/skills/        Codex App local project skills
 .codex/agents/        Codex App custom agents for Team mode
@@ -679,12 +724,14 @@ vgraph.json
 
 `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 Context Tracking
 
-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 context capsules for the current mission.
+TriWiki is the harness-level context-tracking SSOT and 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 context capsules for the current mission.
 
 The default model is anchor-first rather than lossy-summary-first. Selected claims are included as text, while non-selected claims are preserved as LLM Wiki anchors with id, source path, hash, RGBA key, and a compact coordinate tuple. Later turns can hydrate the missing context from the project wiki instead of depending on a one-way summary.
 
+Use TriWiki for long-running routes, Team handoffs, Ralph continuations, research loops, DB reviews, and any task likely to hit context pressure.
+
 RGBA wiki coordinates use four channels:
 
 ```text
@@ -701,7 +748,7 @@ Useful commands:
 ```bash
 sks wiki coords --rgba 12,34,56,255
 sks wiki pack
-sks wiki validate
+sks wiki validate .sneakoscope/wiki/context-pack.json
 ```
 
 Default context layers:
@@ -746,7 +793,7 @@ npm run doctor
 
 `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 sizecheck` blocks accidental package bloat during `release:check`, `publish:dry`, and `npm publish`. Defaults: packed tarball `<=112 KiB`, unpacked package `<=400 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/package.json

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