sneakoscope 0.6.7 → 0.6.9

package/README.md

@@ -6,14 +6,35 @@
 
 <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://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 >=20.11" src="https://img.shields.io/badge/node-%3E%3D20.11-339933.svg">
 </p>
 
+<p align="center">
+  <a href="https://api.npmjs.org/downloads/point/last-week/sneakoscope">Weekly downloads</a>
+  ·
+  <a href="https://api.npmjs.org/downloads/point/last-month/sneakoscope">Monthly downloads</a>
+</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.
 
+## Why Developers Star Sneakoscope Codex
+
+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.
+- **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.
+
+## 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`.
+
 ```bash
 npm i -g sneakoscope
 sks
@@ -277,7 +298,11 @@ 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, database safety guards, H-Proof completion gates, 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, LLM Wiki context continuity, and bounded runtime state.
+
+### Who should use Sneakoscope Codex?
+
+Use Sneakoscope Codex when you want a local CLI harness for agentic coding, Codex App workflows, OpenAI Codex command routing, database-safe automation, long-running implementation tasks, or multi-agent software engineering.
 
 ### Does Sneakoscope Codex support Codex multi-agent teams?
 
@@ -289,7 +314,11 @@ 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, 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, LLM Wiki context continuity, and practical autonomous coding loops.
+
+### What GitHub topics fit this project?
+
+Recommended repository topics are `openai-codex`, `codex-cli`, `codex-app`, `ai-agents`, `agent-orchestration`, `multi-agent`, `developer-tools`, `database-safety`, `supabase`, `mcp`, `context-engineering`, `llm-wiki`, `autoresearch`, and `agentic-coding`.
 
 ## Team Workflow
 
@@ -597,7 +626,6 @@ sks hproof check latest
 .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
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "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",
@@ -46,16 +46,24 @@
     "sneakoscope",
     "codex",
     "sks",
+    "openai",
+    "openai-codex",
     "cli",
+    "developer-tools",
+    "ai-coding",
     "ai-agent",
     "ai-agents",
+    "agentic-coding",
     "harness",
     "codex-cli",
     "codex-app",
+    "codex-hooks",
+    "codex-agents",
     "multi-agent",
     "subagents",
     "agent-orchestration",
     "agent-team",
+    "prompt-router",
     "ralph",
     "research",
     "autoresearch",
@@ -63,6 +71,8 @@
     "update-check",
     "hypothesis",
     "discovery",
+    "context-engineering",
+    "llm-context",
     "llm-wiki",
     "wiki-coordinate",
     "context-compression",

package/src/cli/main.mjs

@@ -789,7 +789,7 @@ async function setup(args) {
   if (localOnly) console.log('Git:       local-only (.git/info/exclude; existing AGENTS.md not modified)');
   console.log(`Codex App: .codex/config.toml, .codex/hooks.json, .codex/skills, .codex/agents, .codex/SNEAKOSCOPE.md`);
   console.log(`Prompt:    default optimization pipeline, $DF fast design/content route`);
-  console.log(`Skills:    .codex/skills, .agents/skills`);
+  console.log(`Skills:    .codex/skills`);
   console.log(`Next:      sks selftest --mock; sks commands; sks dollar-commands`);
   if (!install.ok && install.scope === 'global') console.log('\nGlobal command missing. Run: npm i -g sneakoscope');
   if (!install.ok && install.scope === 'project') console.log('\nProject package missing. Run: npm i -D sneakoscope');
@@ -854,7 +854,7 @@ async function doctor(args) {
     sneakoscope: { ok: await exists(path.join(root, '.sneakoscope')) },
     db_guard: { ok: dbPolicyExists && dbScan.ok, policy: dbPolicyExists ? await loadDbSafetyPolicy(root) : null, scan: dbScan },
     hooks: { ok: await exists(path.join(root, '.codex', 'hooks.json')) },
-    skills: { ok: (await exists(path.join(root, '.codex', 'skills'))) && (await exists(path.join(root, '.agents', 'skills'))) },
+    skills: { ok: await exists(path.join(root, '.codex', 'skills')) },
     codex_app: {
       ...codexApp,
       ok: codexApp.config.ok && codexApp.hooks.ok && codexApp.skills.ok && codexApp.agents.ok && codexApp.quick_reference.ok && codexApp.agents_rules.ok
@@ -873,7 +873,7 @@ async function doctor(args) {
   console.log(`DB Guard:  ${result.db_guard.ok ? 'ok' : 'blocked'} ${dbScan.findings?.length || 0} finding(s)`);
   console.log(`Hooks:     ${result.hooks.ok ? 'ok' : 'missing .codex/hooks.json'}`);
   console.log(`Codex App: ${result.codex_app.ok ? 'ok' : 'missing app files'} .codex/config.toml .codex/hooks.json .codex/skills .codex/agents .codex/SNEAKOSCOPE.md`);
-  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .codex/skills or .agents/skills'}`);
+  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .codex/skills'}`);
   console.log(`Package:   ${result.package.human}`);
   console.log(`Storage:   ${storage.total_human || '0 B'}`);
   console.log(`Ready:     ${result.ready ? 'yes' : 'no'}`);
@@ -1252,8 +1252,8 @@ async function selftest() {
     if (oldSksBin === undefined) delete process.env.SKS_BIN;
     else process.env.SKS_BIN = oldSksBin;
   }
-  const researchSkillExists = await exists(path.join(tmp, '.agents', 'skills', 'research-discovery', 'SKILL.md'));
-  if (!researchSkillExists) throw new Error('selftest failed: research skill not installed');
+  const legacySkillMirrorExists = await exists(path.join(tmp, '.agents', 'skills', 'research-discovery', 'SKILL.md'));
+  if (legacySkillMirrorExists) throw new Error('selftest failed: legacy .agents/skills mirror still installed');
   const codexAppSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'research-discovery', 'SKILL.md'));
   if (!codexAppSkillExists) throw new Error('selftest failed: Codex App skill not installed');
   const dfSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'DF', 'SKILL.md'));
@@ -1439,7 +1439,7 @@ async function projectWikiClaims(root) {
   const claims = [
     ['wiki-hooks', '.codex/hooks.json routes UserPromptSubmit, tool, permission, and Stop events through SKS guards.', '.codex/hooks.json', 'code', 'high'],
     ['wiki-config', '.codex/config.toml enables Codex App profiles, multi-agent support, and Team agent limits.', '.codex/config.toml', 'code', 'high'],
-    ['wiki-skills', '.codex/skills and .agents/skills provide local routes for DF, Team, Ralph, Research, AutoResearch, DB, GX, wiki, and evaluation workflows.', '.codex/skills', 'code', 'medium'],
+    ['wiki-skills', '.codex/skills provides local routes for DF, Team, Ralph, Research, AutoResearch, DB, GX, wiki, and evaluation workflows.', '.codex/skills', 'code', 'medium'],
     ['wiki-agents', '.codex/agents defines Team planning, implementation, DB safety, and QA reviewer roles.', '.codex/agents', 'code', 'medium'],
     ['wiki-policy', '.sneakoscope/policy.json stores update-check, honest-mode, retention, database, performance, and prompt-pipeline policy.', '.sneakoscope/policy.json', 'contract', 'high'],
     ['wiki-memory', '.sneakoscope/memory stores Q0 raw, Q1 evidence, Q2 facts, Q3 tags, and Q4 control bits for hydratable context.', '.sneakoscope/memory', 'wiki', 'high'],

package/src/core/evaluation.mjs

@@ -38,7 +38,7 @@ export function defaultEvaluationScenario() {
     ['req-wiki-rgba', 'TriWiki stores RGBA-derived trigonometric wiki anchors so compressed context remains hydratable by id, hash, source, and coordinate.', 'code', 'high', 1.2],
     ['req-retention', 'runtime logs and mission artifacts are bounded through retention policy and sks gc.', 'code', 'medium', 0.85],
     ['req-selftest', 'selftest covers contract sealing, DB guard blocking, done-gate evaluation, GX render/validate/drift, snapshot, and retention report.', 'test', 'high', 1.1],
-    ['req-skill', 'sks init installs local skills under .agents/skills so project workflows can trigger domain-specific guidance.', 'code', 'medium', 0.9],
+    ['req-skill', 'sks init installs one canonical local skill set under .codex/skills so project workflows can trigger domain-specific guidance without duplicate commands.', 'code', 'medium', 0.9],
     ['req-design', 'design artifact work should gather design context, build an HTML artifact, expose variations when useful, and verify rendered output.', 'code', 'medium', 0.8]
   ];
   const noise = [

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.6.7';
+export const PACKAGE_VERSION = '0.6.9';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/init.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import fsp from 'node:fs/promises';
 import { ensureDir, readJson, readText, writeJsonAtomic, writeTextAtomic, mergeManagedBlock, nowIso, PACKAGE_VERSION, exists } from './fsx.mjs';
 import { DEFAULT_RETENTION_POLICY } from './retention.mjs';
 import { DEFAULT_DB_SAFETY_POLICY } from './db-safety.mjs';
@@ -102,7 +103,7 @@ export async function initProject(root, opts = {}) {
   const hookCommandPrefix = opts.hookCommandPrefix || sksCommandPrefix(installScope, { globalCommand: opts.globalCommand });
   const sine = path.join(root, '.sneakoscope');
   const dirs = [
-    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/wiki', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.codex/skills', '.codex/agents', '.agents/skills'
+    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/wiki', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.codex/skills', '.codex/agents'
   ];
   for (const d of dirs) await ensureDir(path.join(root, d));
   const localExclude = localOnly ? await ensureLocalOnlyGitExclude(root) : null;
@@ -288,9 +289,9 @@ export async function initProject(root, opts = {}) {
   });
   created.push(`.codex/hooks.json (${installScope})`);
 
-  await installSkills(root);
+  const skillInstall = await installSkills(root);
   created.push('.codex/skills/*');
-  created.push('.agents/skills/*');
+  if (skillInstall.removed_legacy_agent_skill_dirs.length) created.push(`.agents/skills legacy mirrors removed (${skillInstall.removed_legacy_agent_skill_dirs.length})`);
   await installCodexAgents(root);
   created.push('.codex/agents/*');
   return { created };
@@ -435,12 +436,44 @@ async function installSkills(root) {
     'design-artifact-expert': `---\nname: design-artifact-expert\ndescription: Create or revise high-fidelity HTML, UI, prototype, deck-like, or visual design artifacts using project design context, variations, and rendered verification.\n---\n\nUse when the user asks for design, UI, prototype, HTML artifact, landing page, deck-like visual work, interaction design, or visual refinement.\n\nWorkflow:\n1. Understand the artifact, audience, constraints, fidelity, variants, and existing brand/design system.\n2. Inspect local code, assets, screenshots, or design-system docs before inventing visuals. If context exists, follow its visual vocabulary.\n3. Build the actual usable screen or artifact first; avoid empty landing-page framing unless the task is explicitly marketing.\n4. Use descriptive HTML filenames. Keep large artifacts split into small support files when needed.\n5. For screens/slides, add data-screen-label attributes for comment context. Slide labels are 1-indexed.\n6. Preserve state for decks, videos, or multi-step prototypes with localStorage when refresh continuity matters.\n7. Expose a small Tweaks surface for useful variants such as layout, density, color, copy, or interaction options.\n8. Verify the artifact renders cleanly in a browser or preview. For design tasks, set done-gate.json design_verification_required/present fields and cite evidence.\n\nQuality bar:\n- Root design decisions in available assets and components.\n- Use restrained, domain-appropriate layout and typography.\n- Avoid text overlap, unreadable controls, decorative clutter, one-note palettes, and placeholder-only deliverables.\n- Prefer icons and familiar controls for tool actions, and make repeated UI dimensions stable.\n`
   };
   for (const [name, content] of Object.entries(skills)) {
-    for (const base of ['.codex/skills', '.agents/skills']) {
-      const dir = path.join(root, base, name);
-      await ensureDir(dir);
-      await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
-    }
+    const dir = path.join(root, '.codex', 'skills', name);
+    await ensureDir(dir);
+    await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
   }
+  return { removed_legacy_agent_skill_dirs: await removeLegacyAgentSkillMirrors(root, Object.keys(skills)) };
+}
+
+async function removeLegacyAgentSkillMirrors(root, skillNames) {
+  const legacyRoot = path.join(root, '.agents', 'skills');
+  if (!(await exists(legacyRoot))) return [];
+  const removed = [];
+  for (const name of skillNames) {
+    const dir = path.join(legacyRoot, name);
+    const skillPath = path.join(dir, 'SKILL.md');
+    const text = await readText(skillPath, null);
+    if (!isGeneratedSksLegacySkill(text, name)) continue;
+    await fsp.rm(dir, { recursive: true, force: true });
+    removed.push(path.relative(root, dir));
+  }
+  await removeDirIfEmpty(legacyRoot);
+  await removeDirIfEmpty(path.join(root, '.agents'));
+  return removed;
+}
+
+function isGeneratedSksLegacySkill(text, name) {
+  if (typeof text !== 'string') return false;
+  return text.startsWith('---') && new RegExp(`^name:\\s*${escapeRegExp(name)}\\s*$`, 'm').test(text);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function removeDirIfEmpty(dir) {
+  try {
+    const entries = await fsp.readdir(dir);
+    if (!entries.length) await fsp.rmdir(dir);
+  } catch {}
 }
 
 async function installCodexAgents(root) {