sneakoscope 0.7.6 → 0.7.13

package/README.md

@@ -2,7 +2,7 @@
 
 ![](https://github.com/mandarange/Sneakoscope-Codex/raw/dev/docs/assets/sneakoscope-codex-logo.png)
 
-Sneakoscope Codex (`sks`, displayed as `ㅅㅋㅅ`) is a Codex CLI/App harness for repeatable agent workflows. It adds terminal commands, Codex App `$` prompt commands, warp-native CLI workspaces, Team/QA/Research routes, inspectable pipeline plans, a maximum-speed Computer Use lane, a fast Goal bridge for native `/goal` persistence, Context7 evidence checks, DB safety, TriWiki context tracking, lightweight skill dreaming, Honest Mode, and release-readiness gates.
+Sneakoscope Codex (`sks`, displayed as `ㅅㅋㅅ`) is a Codex CLI/App harness for repeatable agent workflows. It adds terminal commands, Codex App `$` prompt commands, tmux-native CLI workspaces, Team/QA/Research routes, inspectable pipeline plans, a maximum-speed Computer Use lane, a fast Goal bridge for native `/goal` persistence, Context7 evidence checks, DB safety, TriWiki context tracking, lightweight skill dreaming, Honest Mode, and release-readiness gates.
 
 ## Quick Start
 
@@ -43,17 +43,19 @@ sks selftest --mock
 
 | Area | What it does |
 | --- | --- |
-| CLI runtime | `sks warp open` and `sks --mad` explicitly launch Codex CLI with Warp; bare `sks` only prints help/readiness surfaces. |
-| Codex App commands | Installs generated skills so `$Team`, `$From-Chat-IMG`, `$DFix`, `$QA-LOOP`, `$Goal`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
+| CLI runtime | `sks tmux open` and `sks --mad` explicitly launch Codex CLI with tmux; bare `sks` only prints help/readiness surfaces. |
+| Codex App commands | Installs generated skills so `$Team`, `$From-Chat-IMG`, `$DFix`, `$QA-LOOP`, `$PPT`, `$Goal`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
 | Pipeline plans | Writes `pipeline-plan.json` for stateful routes so the runtime lane, kept stages, skipped stages, verification commands, and no-unrequested-fallback invariant are visible with `sks pipeline plan`. |
 | Team orchestration | Runs substantial work through ambiguity handling, scouts, TriWiki refresh, debate, runtime task graphs, worker inboxes, implementation, review, cleanup, reflection, and Honest Mode; narrow work should use Proof Field evidence to skip unrelated pipeline work instead of expanding Team. |
 | Skill dreaming | Records cheap generated-skill usage counters in JSON and only periodically scans `.agents/skills` for keep, merge, prune, and improvement candidates. Reports are recommendation-only and never delete skills automatically. |
 | From-Chat-IMG | Turns chat screenshots plus original attachments into source-bound work orders, then requires scoped QA evidence before completion. |
 | QA loop | Dogfoods UI/API behavior with safety gates, Codex Computer Use-only UI evidence, safe fixes, and rechecks. |
+| PPT pipeline | Uses `$PPT` for simple, restrained, information-first HTML/PDF presentation artifacts, first asking delivery context, audience profile, STP strategy, decision context, and 3+ pain-point to solution/aha mappings before source research, design-system work, HTML/PDF export, and render QA. Independent strategy/render/file-write phases run in parallel where inputs allow and are recorded in `ppt-parallel-report.json`; editable source HTML is preserved under `source-html/`, PPT-only temporary build files are cleaned after completion, and generated image assets must prefer Codex App built-in image generation through `$imagegen`. |
 | Computer Use fast lane | Uses `$Computer-Use` / `$CU` for UI/browser/visual work that needs maximum speed: skip Team debate and upfront TriWiki loops, use Codex Computer Use directly, then refresh/validate TriWiki and run Honest Mode at final closeout. |
 | Goal | Provides a fast SKS bridge overlay for Codex native persisted `/goal` create, pause, resume, and clear controls; implementation continues through the selected SKS execution route. |
 | TriWiki voxels | Maintains `.sneakoscope/wiki/context-pack.json` as the context SSOT with coordinate anchors, voxel metadata, `attention.use_first`, and `attention.hydrate_first`. |
 | Context7 | Requires current docs for external packages, APIs, MCPs, SDKs, and framework/runtime behavior when correctness depends on current guidance. |
+| getdesign.md | Grounds `design.md`, UI/UX design systems, and presentation-like HTML/PDF artifacts in the official getdesign.md reference and Codex skill path. |
 | DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk. |
 | Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run publishing. |
 
@@ -63,21 +65,21 @@ sks selftest --mock
 - npm
 - Codex CLI for terminal workflows
 - Codex App for app-facing workflows, with Codex Computer Use required for UI/browser evidence
-- Warp for the CLI-first runtime
+- tmux for the CLI-first runtime
 - Context7 MCP for current-docs-gated routes
 
-Install Warp from [warp.dev/download](https://www.warp.dev/download). On macOS, Homebrew users can also install it with:
+Install tmux from [tmux.dev/download](https://www.tmux.dev/download). On macOS, Homebrew users can also install it with:
 
 ```sh
-brew install --cask warp
+brew install tmux
 ```
 
 `sks --mad` is stricter than the normal runtime path:
 
 - Checks npm for a newer `sneakoscope` before launch and asks whether to update when the terminal can answer y/n.
 - Installs the latest Codex CLI with `npm i -g @openai/codex@latest` when it is missing and you approve or pass `--yes`.
-- Requires Warp to be installed before opening the Launch Configuration.
-- Writes a named Warp Launch Configuration and opens it through `warp://launch/<name>.yaml`.
+- Requires tmux 3.x or newer before opening the session.
+- Creates or reuses a named detached tmux session, splits panes, and prints the attach command.
 
 ## Installation
 
@@ -95,6 +97,8 @@ sks bootstrap
 
 Project setup writes shared `.gitignore` entries for generated SKS files: `.sneakoscope/`, `.codex/`, `.agents/`, and managed `AGENTS.md`. Use `sks setup --local-only` when you want those excludes kept only in `.git/info/exclude`.
 
+During npm postinstall, SKS also installs generated Codex App skills and tries the official getdesign Codex skill command, `skills add MohtashamMurshid/getdesign`, when the `skills` CLI is available. If that CLI is missing, setup still installs the generated `getdesign-reference` skill so UI/UX and presentation design-system work keeps using [getdesign.md](https://getdesign.md/) as a required reference.
+
 ### One-Shot Install
 
 Use this when you do not want to keep a global install:
@@ -148,30 +152,30 @@ sks --version
 ```sh
 sks bootstrap
 sks deps check
-sks deps install warp
+sks deps install tmux
 sks codex-app check
 sks doctor --fix
 sks fix-path
 ```
 
-### Open Codex CLI With Warp
+### Open Codex CLI With tmux
 
 ```sh
-sks warp open
-sks warp check
-sks warp status --once
+sks tmux open
+sks tmux check
+sks tmux status --once
 ```
 
-`sks warp open` writes a Warp Launch Configuration for Codex CLI and opens it through Warp's public URI scheme only when that is explicitly requested. When it is already running inside Warp, SKS runs Codex in the current terminal session instead of opening another Warp window. `sks` and `sks warp check` are diagnostic/help surfaces and do not start a workspace.
+`sks tmux open` creates or reuses a named tmux session for Codex CLI only when that is explicitly requested. `sks` and `sks tmux check` are diagnostic/help surfaces and do not start a workspace.
 
-### MAD Warp Launch
+### MAD tmux Launch
 
 ```sh
 sks --mad
 sks --mad --yes
 ```
 
-This creates/uses the `sks-mad-high` Codex profile for a one-shot full-access, high-reasoning Warp launch with `approval_policy = "on-request"` and `approvals_reviewer = "auto_review"`. It is scoped to that explicit command and does not change normal SKS/DB safety defaults. Repeat launches overwrite the same named SKS MAD Launch Configuration.
+This creates/uses the `sks-mad-high` Codex profile for a one-shot full-access, high-reasoning tmux session with `approval_policy = "on-request"` and `approvals_reviewer = "auto_review"`. It is scoped to that explicit command and does not change normal SKS/DB safety defaults. Repeat launches reuse the same named SKS MAD tmux session.
 
 MAD does not disable the pipeline contract: stages, executors, reviewers, and auto-review policy still must not invent unrequested fallback implementation code. If the requested path cannot be implemented, SKS should block with evidence rather than add substitute behavior.
 
@@ -190,19 +194,19 @@ sks team "implement this feature" executor:3 reviewer:1
 sks team watch latest
 sks team lane latest --agent analysis_scout_1 --follow
 sks team message latest --from analysis_scout_1 --to executor_1 --message "handoff note"
-sks team cleanup-warp latest
+sks team cleanup-tmux latest
 sks team status latest
 sks team dashboard latest
 sks team log latest
 ```
 
-Team mode prepares the mission, records live events, compiles runtime tasks and worker inboxes, writes schema-backed effort/work-order/dashboard artifacts, and opens a named Warp Team Launch Configuration with split live lanes when Warp is available. `sks team dashboard` renders the cockpit panes for mission overview, agent lanes, task DAG, QA/dogfood, artifacts/evidence, and performance.
+Team mode prepares the mission, records live events, compiles runtime tasks and worker inboxes, writes schema-backed effort/work-order/dashboard artifacts, and opens a named tmux Team session with split live lanes when tmux is available. `sks team dashboard` renders the cockpit panes for mission overview, agent lanes, task DAG, QA/dogfood, artifacts/evidence, and performance.
 
-The Warp Team launch is a live orchestration screen: the first pane follows `sks team watch <mission-id> --follow` as the mission overview, and neighboring split panes follow individual `sks team lane <mission-id> --agent <name> --follow` views. SKS gives lanes role-specific colors, labels, and terminal titles, so scouts, planning/debate voices, executors, reviewers, and safety lanes are visually distinct while the same evidence is mirrored into `team-transcript.jsonl`, `team-live.md`, and `team-dashboard.json`.
+The tmux Team launch is a live orchestration screen: the first pane follows `sks team watch <mission-id> --follow` as the mission overview, and neighboring split panes follow individual `sks team lane <mission-id> --agent <name> --follow` views. SKS gives lanes role-specific colors, labels, and terminal titles, so scouts, planning/debate voices, executors, reviewers, and safety lanes are visually distinct while the same evidence is mirrored into `team-transcript.jsonl`, `team-live.md`, and `team-dashboard.json`.
 
 Agent sessions communicate through the bounded Team transcript. Use `sks team message <mission-id|latest> --from <agent> --to <agent|all> --message "..."` to add direct or broadcast messages; lane panes show messages addressed to that agent plus the fallback global tail.
 
-When the Team route reaches `session_cleanup`, SKS marks the Warp launch record complete and asks `watch --follow` / `lane --follow` panes to show a cleanup summary and stop. You can also run `sks team cleanup-warp <mission-id|latest>` manually, or `sks team cleanup-warp latest --close` to remove the generated Launch Configuration. Warp's public URI/Launch Configuration surface does not expose a live pane-close API, so the panes remain user-controlled.
+When the Team route reaches `session_cleanup`, SKS marks the tmux session record complete and asks `watch --follow` / `lane --follow` panes to show a cleanup summary and stop. You can also run `sks team cleanup-tmux <mission-id|latest>` manually, or `sks team cleanup-tmux latest --close` to kill the recorded tmux session.
 
 ### QA, Computer Use, Goal, Research, DB, Wiki, GX
 
@@ -278,7 +282,7 @@ Default setup adds these generated SKS paths to the project `.gitignore`; `--loc
 
 Use `sks dollar-commands` to confirm that terminal discovery and Codex App prompt commands agree.
 
-TriWiki is intentionally sparse: `sks wiki sweep` records demote, soft-forget, archive, delete, promote-to-skill, and promote-to-rule candidates instead of injecting every old claim into future prompts. `sks harness fixture` validates the broader Harness Growth Factory contract: deliberate forgetting fixtures, skill card metadata, experiment schema, tool-error taxonomy, permission profiles, MultiAgentV2 defaults, and Warp cockpit view coverage. `sks code-structure scan` flags handwritten files above 1000/2000/3000-line thresholds so new logic can be extracted before command files become harder to maintain.
+TriWiki is intentionally sparse: `sks wiki sweep` records demote, soft-forget, archive, delete, promote-to-skill, and promote-to-rule candidates instead of injecting every old claim into future prompts. `sks harness fixture` validates the broader Harness Growth Factory contract: deliberate forgetting fixtures, skill card metadata, experiment schema, tool-error taxonomy, permission profiles, MultiAgentV2 defaults, and tmux cockpit view coverage. `sks code-structure scan` flags handwritten files above 1000/2000/3000-line thresholds so new logic can be extracted before command files become harder to maintain.
 
 ## Prompt `$` Commands
 
@@ -318,8 +322,8 @@ sks selftest --mock
 ### Start A CLI Workspace
 
 ```sh
-sks warp check
-sks warp open
+sks tmux check
+sks tmux open
 ```
 
 For the high-reasoning full-access profile:
@@ -381,14 +385,14 @@ npm install -g .
 
 If the global command is stale, reinstall globally from the repo or from npm.
 
-### Warp is missing
+### tmux is missing
 
 ```sh
-sks deps install warp
-sks warp check
+sks deps install tmux
+sks tmux check
 ```
 
-Install Warp from [warp.dev/download](https://www.warp.dev/download) or run `brew install --cask warp` on macOS, then re-run `sks warp check`.
+Install tmux from [tmux.dev/download](https://www.tmux.dev/download) or run `brew install tmux` on macOS, then re-run `sks tmux check`.
 
 ### Codex App tools are missing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.7.6",
+  "version": "0.7.13",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -57,7 +57,7 @@
     "harness",
     "codex-cli",
     "codex-app",
-    "warp",
+    "tmux",
     "auto-review",
     "browser-use",
     "computer-use",

package/src/cli/context7-command.mjs

@@ -0,0 +1,163 @@
+import { projectRoot, readJson, runProcess, sksRoot } from '../core/fsx.mjs';
+import { getCodexInfo } from '../core/codex-adapter.mjs';
+import { context7Docs, context7Resolve, context7Text, context7Tools } from '../core/context7-client.mjs';
+import { context7Evidence, recordContext7Evidence } from '../core/pipeline.mjs';
+import { stateFile } from '../core/mission.mjs';
+import { checkContext7, ensureProjectContext7Config } from './install-helpers.mjs';
+
+const flag = (args, name) => args.includes(name);
+
+export async function context7Command(sub = 'check', args = []) {
+  const action = sub || 'check';
+  const setupScope = action === 'setup' ? readOption(args, '--scope', flag(args, '--global') ? 'global' : 'project') : null;
+  const root = action === 'setup' && setupScope === 'project' ? await projectRoot() : await sksRoot();
+  if (action === 'check') {
+    const result = await checkContext7(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 MCP\n');
+    console.log(`Project config: ${result.project.ok ? 'ok' : 'missing'} ${result.project.path}`);
+    console.log(`Global config:  ${result.global.ok ? 'ok' : 'missing'} ${result.global.path}`);
+    console.log(`Codex mcp list: ${result.codex_mcp_list.ok ? 'ok' : result.codex_mcp_list.checked ? 'missing' : 'not checked'}`);
+    console.log(`Ready:          ${result.ok ? 'yes' : 'no'}`);
+    if (!result.ok) console.log('\nRun: sks context7 setup --scope project');
+    return;
+  }
+  if (action === 'tools') {
+    const result = await context7Tools({ timeoutMs: readNumberOption(args, '--timeout-ms', 30000) });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 Local MCP Tools\n');
+    console.log(`Server: ${result.server.info?.name || 'context7'} ${result.server.info?.version || ''}`.trim());
+    console.log(`Command: ${result.server.command} ${result.server.args.join(' ')}`);
+    console.log(`Tools:  ${result.tool_names.join(', ') || 'none'}`);
+    if (!result.tool_names.includes('resolve-library-id') || !result.tool_names.some((name) => name === 'query-docs' || name === 'get-library-docs')) {
+      process.exitCode = 1;
+      console.log('\nContext7 local MCP is missing the required resolve/docs tools.');
+    }
+    return;
+  }
+  if (action === 'resolve') {
+    const positional = positionalArgs(args);
+    const libraryName = positional.join(' ').trim();
+    if (!libraryName) throw new Error('Usage: sks context7 resolve <library-name> [--query "..."] [--json]');
+    const result = await context7Resolve(libraryName, {
+      query: readOption(args, '--query', libraryName),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 Resolve\n');
+    console.log(`Library: ${libraryName}`);
+    console.log(`ID:      ${result.library_id || 'not resolved'}`);
+    console.log(`Server:  ${result.server.info?.name || 'context7'} ${result.server.info?.version || ''}`.trim());
+    const text = context7Text(result.result).split(/\n/).slice(0, 24).join('\n').trim();
+    if (text) console.log(`\n${text}`);
+    if (!result.ok || !result.library_id) process.exitCode = 1;
+    return;
+  }
+  if (action === 'docs') {
+    const positional = positionalArgs(args);
+    const libraryNameOrId = positional.join(' ').trim();
+    if (!libraryNameOrId) throw new Error('Usage: sks context7 docs <library-name|/org/project> [--query "..."] [--topic "..."] [--tokens N] [--json]');
+    const result = await context7Docs(libraryNameOrId, {
+      query: readOption(args, '--query', readOption(args, '--topic', libraryNameOrId)),
+      topic: readOption(args, '--topic', libraryNameOrId),
+      tokens: readNumberOption(args, '--tokens', 2000),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    printContext7DocsResult(result, { title: 'SKS Context7 Docs' });
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'evidence') {
+    const positional = positionalArgs(args);
+    const missionArg = positional.shift();
+    const libraryNameOrId = positional.join(' ').trim();
+    if (!missionArg || !libraryNameOrId) throw new Error('Usage: sks context7 evidence <mission-id|latest> <library-name|/org/project> [--query "..."] [--topic "..."] [--tokens N] [--json]');
+    const missionId = await resolveMissionId(root, missionArg);
+    if (!missionId) throw new Error('No mission found for Context7 evidence.');
+    const result = await context7Docs(libraryNameOrId, {
+      query: readOption(args, '--query', readOption(args, '--topic', libraryNameOrId)),
+      topic: readOption(args, '--topic', libraryNameOrId),
+      tokens: readNumberOption(args, '--tokens', 2000),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    const state = { ...(await readJson(stateFile(root), {})), mission_id: missionId };
+    await recordContext7Evidence(root, state, { tool_name: 'resolve-library-id', library: libraryNameOrId, library_id: result.library_id, source: result.resolve ? 'sks context7 evidence' : 'sks context7 evidence explicit-library-id' });
+    if (result.docs_tool) {
+      await recordContext7Evidence(root, state, { tool_name: result.docs_tool, library_id: result.library_id, source: 'sks context7 evidence' });
+    }
+    const evidence = await context7Evidence(root, state);
+    const out = { ...result, mission_id: missionId, evidence };
+    if (flag(args, '--json')) return console.log(JSON.stringify(out, null, 2));
+    printContext7DocsResult(result, { title: 'SKS Context7 Evidence' });
+    console.log(`\nMission:  ${missionId}`);
+    console.log(`Evidence: ${evidence.ok ? 'ok' : 'missing'} resolve=${evidence.resolve ? 'yes' : 'no'} docs=${evidence.docs ? 'yes' : 'no'} events=${evidence.count}`);
+    if (!result.ok || !evidence.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'setup') {
+    const scope = setupScope;
+    const transport = readOption(args, '--transport', flag(args, '--remote') ? 'remote' : 'local');
+    if (!['project', 'global'].includes(scope)) throw new Error('Invalid Context7 scope. Use project or global.');
+    if (!['local', 'remote'].includes(transport)) throw new Error('Invalid Context7 transport. Use local or remote.');
+    if (scope === 'project') {
+      const changed = await ensureProjectContext7Config(root, transport);
+      const result = await checkContext7(root);
+      if (flag(args, '--json')) return console.log(JSON.stringify({ changed, ...result }, null, 2));
+      console.log(`Context7 project MCP ${changed ? 'configured' : 'already configured'} in .codex/config.toml`);
+      console.log(`Ready: ${result.ok ? 'yes' : 'no'}`);
+      return;
+    }
+    const codex = await getCodexInfo();
+    if (!codex.bin) throw new Error('Codex CLI missing. Install separately: npm i -g @openai/codex, or set SKS_CODEX_BIN.');
+    const cmdArgs = transport === 'remote'
+      ? ['mcp', 'add', 'context7', '--url', 'https://mcp.context7.com/mcp']
+      : ['mcp', 'add', 'context7', '--', 'npx', '-y', '@upstash/context7-mcp@latest'];
+    const result = await runProcess(codex.bin, cmdArgs, { timeoutMs: 30000, maxOutputBytes: 64 * 1024 });
+    if (flag(args, '--json')) return console.log(JSON.stringify({ command: `${codex.bin} ${cmdArgs.join(' ')}`, result }, null, 2));
+    if (result.code !== 0) throw new Error(result.stderr || result.stdout || 'codex mcp add failed');
+    console.log('Context7 global MCP configured.');
+    return;
+  }
+  throw new Error(`Unknown context7 command: ${action}`);
+}
+
+function printContext7DocsResult(result, opts = {}) {
+  console.log(`${opts.title || 'SKS Context7 Docs'}\n`);
+  console.log(`Library ID: ${result.library_id || 'not resolved'}`);
+  console.log(`Docs tool:  ${result.docs_tool || 'missing'}`);
+  console.log(`Server:     ${result.server?.info?.name || 'context7'} ${result.server?.info?.version || ''}`.trim());
+  const text = context7Text(result.docs).split(/\n/).slice(0, 48).join('\n').trim();
+  if (text) console.log(`\n${text}`);
+  if (result.error) console.log(`\nError: ${result.error}`);
+}
+
+function readOption(args, name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+function readNumberOption(args, name, fallback) {
+  const raw = readOption(args, name, null);
+  if (raw == null) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function positionalArgs(args = []) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (String(arg).startsWith('--')) {
+      if (args[i + 1] && !String(args[i + 1]).startsWith('--')) i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+async function resolveMissionId(root, arg) {
+  const { findLatestMission } = await import('../core/mission.mjs');
+  return (!arg || arg === 'latest') ? findLatestMission(root) : arg;
+}