sneakoscope 0.6.6 → 0.6.7

package/README.md

@@ -28,6 +28,14 @@ sks setup
 sks doctor --fix
 ```
 
+Use local-only setup when the generated SKS files must never appear in git status:
+
+```bash
+sks setup --local-only
+```
+
+This writes repo-local excludes to `.git/info/exclude` for `.sneakoscope/`, `.codex/`, `.agents/`, and `AGENTS.md`. If `AGENTS.md` already exists, local-only setup does not modify it.
+
 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.
 
@@ -378,10 +386,10 @@ sks aliases
 sks --help
 sneakoscope --help
 
-sks setup [--install-scope global|project] [--force] [--json]
+sks setup [--install-scope global|project] [--local-only] [--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 doctor [--fix] [--local-only] [--json] [--install-scope global|project]
+sks init [--force] [--local-only] [--install-scope global|project]
 sks selftest [--mock]
 
 sks ralph prepare "task"

package/package.json

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

package/src/cli/main.mjs

@@ -50,10 +50,10 @@ const COMMAND_CATALOG = [
   { name: 'dollar-commands', usage: 'sks dollar-commands [--json]', description: 'List Codex App $ commands such as $DF.' },
   { name: 'df', usage: 'sks df', description: 'Explain $DF fast design/content fix mode.' },
   { name: 'aliases', usage: 'sks aliases', description: 'Show command aliases and npm binary names.' },
-  { name: 'setup', usage: 'sks setup [--install-scope global|project] [--force] [--json]', description: 'Initialize SKS state, Codex App files, hooks, skills, and rules.' },
+  { name: 'setup', usage: 'sks setup [--install-scope global|project] [--local-only] [--force] [--json]', description: 'Initialize SKS state, Codex App files, hooks, skills, and rules.' },
   { name: 'fix-path', usage: 'sks fix-path [--install-scope global|project] [--json]', description: 'Refresh hook commands with the resolved SKS binary path.' },
-  { name: 'doctor', usage: 'sks doctor [--fix] [--json] [--install-scope global|project]', description: 'Check Node, Codex CLI, install scope, hooks, skills, DB guard, and Codex App files.' },
-  { name: 'init', usage: 'sks init [--force] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
+  { name: 'doctor', usage: 'sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]', description: 'Check Node, Codex CLI, install scope, hooks, skills, DB guard, and Codex App files.' },
+  { name: 'init', usage: 'sks init [--force] [--local-only] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
   { name: 'selftest', usage: 'sks selftest [--mock]', description: 'Run local smoke tests without calling a model.' },
   { name: 'ralph', usage: 'sks ralph prepare|answer|run|status ...', description: 'Run mandatory-clarification Ralph missions with a no-question execution loop.' },
   { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run frontier-style research missions with novelty and falsification gates.' },
@@ -134,10 +134,10 @@ Usage:
   sks dollar-commands [--json]
   sks df
   sks aliases
-  sks setup [--install-scope global|project] [--force] [--json]
+  sks setup [--install-scope global|project] [--local-only] [--force] [--json]
   sks fix-path [--install-scope global|project] [--json]
-  sks doctor [--fix] [--json] [--install-scope global|project]
-  sks init [--install-scope global|project]
+  sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]
+  sks init [--install-scope global|project] [--local-only]
   sks selftest [--mock]
   sks ralph prepare "task"
   sks ralph answer <mission-id|latest> <answers.json>
@@ -326,6 +326,11 @@ Project-only install:
   npm i -D sneakoscope
   npx sks setup --install-scope project
 
+Local-only install artifacts:
+  sks setup --local-only
+  # writes generated SKS files but excludes .sneakoscope/, .codex/, .agents/, AGENTS.md through .git/info/exclude
+  # existing AGENTS.md is not modified in local-only mode
+
 GitHub install for unreleased commits:
   npm i -g git+${REPOSITORY_URL}
 `);
@@ -563,6 +568,11 @@ Project-only install:
   npm i -D sneakoscope
   npx sks setup --install-scope project
 
+Local-only install artifacts:
+  sks setup --local-only
+  # excludes .sneakoscope/, .codex/, .agents/, AGENTS.md through .git/info/exclude
+  # existing AGENTS.md is not modified in local-only mode
+
 GitHub install for unreleased commits:
   npm i -g git+${REPOSITORY_URL}
   sks setup
@@ -750,8 +760,9 @@ Render and verify:
 async function setup(args) {
   const root = await projectRoot();
   const installScope = installScopeFromArgs(args);
+  const localOnly = flag(args, '--local-only');
   const globalCommand = await globalSksCommand();
-  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand, localOnly });
   const install = await installStatus(root, installScope, { globalCommand });
   const hooksPath = path.join(root, '.codex', 'hooks.json');
   const result = {
@@ -767,6 +778,7 @@ async function setup(args) {
       agents_rules: path.join(root, 'AGENTS.md')
     },
     created: res.created,
+    local_only: localOnly,
     next: ['sks selftest --mock', 'sks doctor', 'sks commands']
   };
   if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
@@ -774,6 +786,7 @@ async function setup(args) {
   console.log(`Project:   ${root}`);
   console.log(`Install:   ${install.ok ? 'ok' : 'missing'} ${install.scope} (${install.command_prefix})`);
   console.log(`Hooks:     ${path.relative(root, hooksPath)}`);
+  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`);
@@ -789,7 +802,7 @@ async function fixPath(args) {
     ? installScopeFromArgs(args)
     : normalizeInstallScope(manifest?.installation?.scope || 'global');
   const globalCommand = await globalSksCommand();
-  await initProject(root, { installScope, globalCommand });
+  await initProject(root, { installScope, globalCommand, localOnly: flag(args, '--local-only') || Boolean(manifest?.git?.local_only) });
   const install = await installStatus(root, installScope, { globalCommand });
   const result = {
     root,
@@ -814,7 +827,8 @@ async function doctor(args) {
     : null;
   if (flag(args, '--fix')) {
     const fixScope = requestedScope || 'global';
-    await initProject(root, { installScope: fixScope, globalCommand: await globalSksCommand() });
+    const existingManifest = await readJson(path.join(root, '.sneakoscope', 'manifest.json'), null);
+    await initProject(root, { installScope: fixScope, globalCommand: await globalSksCommand(), localOnly: flag(args, '--local-only') || Boolean(existingManifest?.git?.local_only) });
   }
   const codex = await getCodexInfo();
   const rust = await rustInfo();
@@ -872,10 +886,12 @@ async function doctor(args) {
 async function init(args) {
   const root = await projectRoot();
   const installScope = installScopeFromArgs(args);
+  const localOnly = flag(args, '--local-only');
   const globalCommand = await globalSksCommand();
-  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand, localOnly });
   console.log(`Initialized Sneakoscope Codex in ${root}`);
   console.log(`Install scope: ${installScope} (${sksCommandPrefix(installScope, { globalCommand })})`);
+  if (localOnly) console.log('Git mode: local-only (.git/info/exclude)');
   for (const x of res.created) console.log(`- ${x}`);
 }
 
@@ -1207,6 +1223,16 @@ async function selftest() {
   await initProject(projectScopeTmp, { installScope: 'project' });
   const projectHooks = await readJson(path.join(projectScopeTmp, '.codex', 'hooks.json'));
   if (projectHooks.hooks.PreToolUse[0].hooks[0].command !== 'node ./node_modules/sneakoscope/bin/sks.mjs hook pre-tool') throw new Error('selftest failed: project install hook command missing');
+  const localOnlyTmp = tmpdir();
+  await ensureDir(path.join(localOnlyTmp, '.git'));
+  await writeTextAtomic(path.join(localOnlyTmp, 'AGENTS.md'), 'existing local rules\n');
+  await initProject(localOnlyTmp, { localOnly: true });
+  const localExclude = await safeReadText(path.join(localOnlyTmp, '.git', 'info', 'exclude'));
+  if (!localExclude.includes('.codex/') || !localExclude.includes('AGENTS.md')) throw new Error('selftest failed: local-only git excludes missing');
+  const localAgents = await safeReadText(path.join(localOnlyTmp, 'AGENTS.md'));
+  if (localAgents.trim() !== 'existing local rules') throw new Error('selftest failed: local-only modified existing AGENTS.md');
+  const localManifest = await readJson(path.join(localOnlyTmp, '.sneakoscope', 'manifest.json'));
+  if (!localManifest.git?.local_only) throw new Error('selftest failed: local-only manifest missing');
   if (!isTransientNpmBinPath('/tmp/.npm/_npx/abc/node_modules/.bin/sks')) throw new Error('selftest failed: npx bin path not recognized as transient');
   if (!isTransientNpmBinPath('/tmp/.npm-cache/_cacache/tmp/git-cloneabc/bin/sks.mjs')) throw new Error('selftest failed: npm cache git clone path not recognized as transient');
   if (isTransientNpmBinPath('/usr/local/bin/sks')) throw new Error('selftest failed: stable global bin marked transient');

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.6';
+export const PACKAGE_VERSION = '0.6.7';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/init.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { ensureDir, readJson, writeJsonAtomic, writeTextAtomic, mergeManagedBlock, nowIso, PACKAGE_VERSION, exists } from './fsx.mjs';
+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';
 
@@ -98,12 +98,15 @@ A task is not done until relevant tests are run or justified, unsupported critic
 export async function initProject(root, opts = {}) {
   const created = [];
   const installScope = normalizeInstallScope(opts.installScope || 'global');
+  const localOnly = Boolean(opts.localOnly);
   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'
   ];
   for (const d of dirs) await ensureDir(path.join(root, d));
+  const localExclude = localOnly ? await ensureLocalOnlyGitExclude(root) : null;
+  if (localExclude?.path) created.push(`${path.relative(root, localExclude.path)} local-only excludes`);
 
   await writeJsonAtomic(path.join(sine, 'manifest.json'), {
     package: 'sneakoscope',
@@ -138,6 +141,11 @@ export async function initProject(root, opts = {}) {
       channel_map: { r: 'domainAngle', g: 'layerRadius', b: 'phase', a: 'concentration' },
       continuity_model: 'selected_text_plus_hydratable_rgba_trig_anchors'
     },
+    git: {
+      local_only: localOnly,
+      exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
+      excluded_patterns: localExclude?.patterns || []
+    },
     database_safety: 'destructive_db_operations_denied_always',
     gx_renderer: 'deterministic_svg_html'
   });
@@ -157,7 +165,13 @@ export async function initProject(root, opts = {}) {
     const policy = await readJson(policyPath, {});
     await writeJsonAtomic(policyPath, {
       ...policy,
-      installation: installPolicy(installScope, hookCommandPrefix)
+      installation: installPolicy(installScope, hookCommandPrefix),
+      git: {
+        ...(policy.git || {}),
+        local_only: localOnly || Boolean(policy.git?.local_only),
+        exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : policy.git?.exclude_path || null,
+        excluded_patterns: localExclude?.patterns || policy.git?.excluded_patterns || []
+      }
     });
   }
 
@@ -165,6 +179,11 @@ export async function initProject(root, opts = {}) {
     return {
       schema_version: 1,
       installation: installPolicy(scope, commandPrefix),
+      git: {
+        local_only: localOnly,
+        exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
+        excluded_patterns: localExclude?.patterns || []
+      },
       retention: DEFAULT_RETENTION_POLICY,
       update_check: {
         enabled: true,
@@ -244,8 +263,13 @@ export async function initProject(root, opts = {}) {
     created.push('.sneakoscope/state/current.json');
   }
 
-  await mergeManagedBlock(path.join(root, 'AGENTS.md'), 'Sneakoscope Codex GX MANAGED BLOCK', AGENTS_BLOCK);
-  created.push('AGENTS.md managed block');
+  const agentsMdPath = path.join(root, 'AGENTS.md');
+  if (localOnly && await exists(agentsMdPath)) {
+    created.push('AGENTS.md skipped (local-only existing file)');
+  } else {
+    await mergeManagedBlock(agentsMdPath, 'Sneakoscope Codex GX MANAGED BLOCK', AGENTS_BLOCK);
+    created.push('AGENTS.md managed block');
+  }
 
   await writeTextAtomic(path.join(root, '.codex', 'config.toml'), `[features]\ncodex_hooks = true\nmulti_agent = true\n\n[agents]\nmax_threads = 6\nmax_depth = 1\n\n[agents.team_consensus]\ndescription = "Planning and debate agent for SKS Team mode. Maps options, constraints, risks, and proposes the agreed objective before implementation starts."\nconfig_file = "./agents/team-consensus.toml"\nnickname_candidates = ["Consensus", "Atlas"]\n\n[agents.implementation_worker]\ndescription = "Implementation worker for SKS Team mode. Owns a clearly bounded write set and coordinates with other workers without reverting their edits."\nconfig_file = "./agents/implementation-worker.toml"\nnickname_candidates = ["Builder", "Mason"]\n\n[agents.db_safety_reviewer]\ndescription = "Read-only database safety reviewer for SQL, migrations, RLS, destructive-operation risk, and rollback safety."\nconfig_file = "./agents/db-safety-reviewer.toml"\nnickname_candidates = ["Sentinel", "Ledger"]\n\n[agents.qa_reviewer]\ndescription = "Read-only verification reviewer for correctness, tests, regressions, and missing evidence."\nconfig_file = "./agents/qa-reviewer.toml"\nnickname_candidates = ["Verifier", "Scout"]\n\n[profiles.sks-ralph]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-research]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "xhigh"\n\n[profiles.sks-team]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-default]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "medium"\n`);
   created.push('.codex/config.toml');
@@ -272,6 +296,32 @@ export async function initProject(root, opts = {}) {
   return { created };
 }
 
+async function ensureLocalOnlyGitExclude(root) {
+  const gitDir = await resolveGitDir(root);
+  if (!gitDir) return { path: null, patterns: [] };
+  const patterns = ['.sneakoscope/', '.codex/', '.agents/', 'AGENTS.md'];
+  const excludePath = path.join(gitDir, 'info', 'exclude');
+  await ensureDir(path.dirname(excludePath));
+  const markerStart = '# Sneakoscope Codex local-only generated files';
+  const current = await readText(excludePath, '');
+  if (!current.includes(markerStart)) {
+    const block = `${markerStart}\n${patterns.join('\n')}\n`;
+    await writeTextAtomic(excludePath, `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}`);
+  }
+  return { path: excludePath, patterns };
+}
+
+async function resolveGitDir(root) {
+  const dotGit = path.join(root, '.git');
+  if (!(await exists(dotGit))) return null;
+  const text = await readText(dotGit, null);
+  if (typeof text === 'string') {
+    const match = text.match(/^gitdir:\s*(.+)\s*$/m);
+    if (match) return path.resolve(root, match[1]);
+  }
+  return dotGit;
+}
+
 function codexAppQuickReference(scope, commandPrefix) {
   return `# Sneakoscope Codex for Codex App