sneakoscope 0.6.24 → 0.6.25

package/README.md

@@ -30,6 +30,7 @@ Sneakoscope Codex is for developers who want Codex CLI to keep working until a g
 - **Database-safe autonomous coding**: destructive SQL, unsafe Supabase MCP writes, production DB mutation, and risky migration flows are blocked or surfaced early.
 - **Harness self-protection**: after setup, installed SKS control files are locked against LLM tool edits, with a source-repo-only exception for Sneakoscope engine development.
 - **Other-harness conflict gate**: OMX/DCodex-style Codex harness traces block npm install and setup until a human-approved cleanup is performed.
+- **Automatic project versioning**: every commit can carry a unique patch version bump, with package-lock sync and a Git common-dir lock for parallel workers.
 - **Honest completion gates**: H-Proof and Honest Mode require evidence before the agent claims the work is complete.
 - **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.
 
@@ -42,7 +43,7 @@ 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. During postinstall, SKS blocks installation if OMX, DCodex, or their global/repo-level traces are detected; the output includes a GPT-5.5 high cleanup prompt and installation cannot continue unless a human approves removal. If no conflicting harness exists, 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.
+`npm i -g sneakoscope` prints setup guidance without making npm output look like a crash. If OMX, DCodex, or their global/repo-level traces are detected during postinstall, npm installation can still finish, but SKS clearly reports that `sks setup` and `sks doctor --fix` are blocked until a human-approved cleanup happens. In an interactive terminal, postinstall asks whether to show the GPT-5.5 high cleanup prompt now; in CI or agent installs, it prints `sks conflicts prompt` for later. If no conflicting harness exists, 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:
 
@@ -103,6 +104,7 @@ sks quickstart
 sks codex-app
 sks dollar-commands
 sks context7 tools
+sks versioning status
 sks df
 sks aliases
 ```
@@ -163,6 +165,24 @@ SKS uses the official Codex hook behavior: `UserPromptSubmit` can inject additio
 
 After setup, SKS writes `.sneakoscope/harness-guard.json`. Hooks block LLM tool calls that try to edit installed harness control files such as `.codex/hooks.json`, `.codex/config.toml`, `.codex/SNEAKOSCOPE.md`, `.agents/skills/`, `.codex/agents/`, `.sneakoscope/manifest.json`, `.sneakoscope/policy.json`, `.sneakoscope/db-safety.json`, `AGENTS.md`, or `node_modules/sneakoscope`. The only automatic exception is the Sneakoscope engine source repository itself, detected from `package.json` name `sneakoscope` plus `bin/sks.mjs` and `src/core/*`.
 
+## Project Versioning
+
+SKS setup installs a managed Git `pre-commit` hook for projects with `package.json`. On every commit, SKS bumps the project patch version before Git writes the commit, syncs `package-lock.json` and `npm-shrinkwrap.json` when present, and stages those version files into the same commit.
+
+Multiple workers and worktrees share a version lock in the Git common directory. If another worker already used a version, the next commit automatically bumps above the last seen version instead of reusing it.
+
+```bash
+sks versioning status
+sks versioning bump
+sks versioning hook
+```
+
+The bypass is intentionally explicit and conversation-local:
+
+```bash
+SKS_DISABLE_VERSIONING=1 git commit ...
+```
+
 Inside Codex App, you can ask the agent to use the local SKS control surface, for example:
 
 ```text
@@ -264,6 +284,7 @@ sks research run latest --max-cycles 3
 - **Forced subagent execution policy**: code-changing work first surfaces SKS status context, then defaults to parallel worker subagents when independent write scopes exist; the parent orchestrator owns integration and verification.
 - **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.
+- **Automatic project versioning**: setup installs a pre-commit guard that bumps `package.json` patch versions, syncs lockfiles, stages them, and avoids duplicate versions across parallel workers.
 - **Honest Mode finish**: final answers must include an evidence-aware verification pass before claiming the goal is complete.
 - **Fast DF mode**: `$DF` handles small design/content edits like color, copy, labels, spacing, and translation without unnecessary Ralph, Research, or evaluation loops.
 - **Database guard**: destructive DB operations, production writes, unsafe Supabase MCP configuration, and direct live SQL mutations are blocked or warned on.
@@ -305,42 +326,9 @@ Team mode uses Codex subagents/custom agents as an orchestration protocol rather
 
 For code-changing work, generated SKS rules tell Codex to surface visible route, guard, write-scope, and verification status before editing. When the work has independent, non-overlapping write scopes, Codex should spawn worker subagents in parallel by default; the parent keeps urgent blockers local, assigns ownership, integrates results, and runs final verification.
 
-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 read-only analysis scouts first, exactly N debate participants next, and then a separate N-person executor development team. `--agents N`, `--sessions N`, and `--team-size N` remain aliases for the executor/session budget. `--max-agents` uses the configured default maximum of 6 sessions/agents. The parent orchestrator is not counted.
+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` creates N read-only analysis scouts, N debate participants, and then a separate N-person executor development team. The parent orchestrator is not counted.
 
-```text
-parallel analysis scouts
-  -> spawn exactly N read-only analysis_scout_N agents
-  -> split repo, docs, tests, API, DB-risk, UX-friction, and implementation-surface investigation
-  -> write source-backed findings and TriWiki-ready claims to team-analysis.md
-
-TriWiki refresh
-  -> parent orchestrator runs sks wiki pack
-  -> parent validates .sneakoscope/wiki/context-pack.json with sks wiki validate
-  -> later debate and implementation handoffs use refreshed anchor-first context
-
-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 debate agents
-
-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
-```
+The pipeline is scout-first: parallel analysis, TriWiki refresh, planning debate, consensus, fresh parallel implementation, review, integration, and Honest Mode evidence.
 
 Create a Team mission:
 
@@ -356,7 +344,7 @@ Inside Codex App, use:
 $Team executor:5 run parallel analysis scouts, refresh TriWiki, agree on the best plan, close the debate team, then implement with a fresh development team
 ```
 
-The generated Team artifacts are:
+Key Team artifacts:
 
 ```text
 .sneakoscope/missions/<MISSION_ID>/team-plan.json
@@ -369,8 +357,6 @@ The generated Team artifacts are:
 .codex/agents/analysis-scout.toml
 .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:
@@ -425,70 +411,45 @@ All terminal examples below use `sks`, but the same commands can be run with the
 
 ```bash
 sks help [topic]
-sks update-check [--json]
 sks wizard
 sks commands [--json]
-sks usage [install|setup|team|ralph|research|db|codex-app|df|dollar|context7|pipeline|reasoning|eval|gx|wiki]
+sks usage [topic]
 sks quickstart
 sks codex-app
 sks dollar-commands [--json]
 sks df
-sks context7 check|setup|tools|resolve|docs|evidence ...
-sks pipeline status|resume [--json]
-sks guard check [--json]
-sks conflicts check|prompt [--json]
-sks reasoning ["prompt"] [--json]
-sks aliases
 
 sks --help
 sneakoscope --help
 
 sks setup [--install-scope global|project] [--local-only] [--force] [--json]
-sks fix-path [--install-scope global|project] [--json]
 sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]
-sks init [--force] [--local-only] [--install-scope global|project]
 sks selftest [--mock]
+sks versioning status|bump|hook
 
 sks ralph prepare "task"
 sks ralph answer <mission-id|latest> <answers.json>
 sks ralph run <mission-id|latest> [--mock] [--max-cycles N]
-sks ralph status <mission-id|latest>
 
 sks research prepare "topic" [--depth frontier]
 sks research run <mission-id|latest> [--mock] [--max-cycles N]
-sks research status <mission-id|latest>
 
-sks db policy
 sks db scan [--migrations] [--json]
-sks db mcp-config --project-ref <ref> [--features database,docs]
-sks db classify --sql "DROP TABLE users"
-sks db classify --command "supabase db reset"
 sks db check --sql "SELECT * FROM users LIMIT 10"
 sks db check --command "supabase db reset"
-sks db check --file ./migration.sql
-
-sks eval run [--json] [--out report.json] [--iterations N]
-sks eval compare --baseline old.json --candidate new.json [--json]
-sks eval thresholds
 
-sks wiki coords --rgba 12,34,56,255
+sks team "task" [executor:5 reviewer:2 user:1] [--json]
+sks team log|tail|watch|status [mission-id|latest]
 sks wiki pack [--json] [--role worker|verifier] [--max-anchors N]
 sks wiki validate [context-pack.json]
-
+sks context7 check|setup|tools|docs ...
+sks pipeline status|resume [--json]
+sks guard check [--json]
+sks conflicts check|prompt [--json]
+sks eval run|compare|thresholds ...
 sks hproof check [mission-id|latest]
-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]
-sks gx drift [name]
-sks gx snapshot [name]
-sks profile show
-sks profile set <model>
+sks gx init|render|validate|drift|snapshot [name]
 sks gc [--dry-run] [--json]
-sks memory [--dry-run] [--json]
-sks stats [--json]
 ```
 
 `sks memory` is currently an alias for garbage collection/retention handling.
@@ -751,7 +712,7 @@ Storage is intentionally bounded:
 - `sks gc` compacts oversized JSONL logs and prunes old artifacts
 - `sks stats` reports package and `.sneakoscope` storage size
 
-See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for the detailed resource policy.
+See the [resource policy](https://github.com/mandarange/Sneakoscope-Codex/blob/main/docs/PERFORMANCE.md) for the detailed storage and leak policy.
 
 ## Visual Cartridges
 
@@ -837,11 +798,10 @@ src/core/init.mjs           project bootstrap and hook/skill installation
 src/core/research.mjs       research-mode plan, novelty ledger, and gate helpers
 src/core/retention.mjs      storage report and garbage collection policy
 src/core/triwiki-attention.mjs
-docs/PERFORMANCE.md         resource and leak policy
 crates/sks-core/         optional Rust helper source, not shipped in npm package
 ```
 
-The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, and `LICENSE`; `.sneakoscope`, `.codex`, `.agents`, Rust sources, archives, and local state are excluded.
+The published npm package is allowlisted to `bin`, `src`, `README.md`, and `LICENSE`; `.sneakoscope`, `.codex`, `.agents`, `docs`, Rust sources, archives, and local state are excluded.
 
 ## Development
 
@@ -856,7 +816,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 `<=132 KiB`, unpacked package `<=470 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 `<=136 KiB`, unpacked package `<=500 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.24",
+  "version": "0.6.25",
   "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",
@@ -23,7 +23,6 @@
   "files": [
     "bin",
     "src",
-    "docs",
     "README.md",
     "LICENSE"
   ],

package/src/cli/main.mjs

@@ -16,6 +16,7 @@ import { classifySql, classifyCommand, loadDbSafetyPolicy, safeSupabaseMcpConfig
 import { checkHarnessModification, harnessGuardStatus, isHarnessSourceProject } from '../core/harness-guard.mjs';
 import { formatHarnessConflictReport, llmHarnessCleanupPrompt, scanHarnessConflicts } from '../core/harness-conflicts.mjs';
 import { context7Docs, context7Resolve, context7Text, context7Tools } from '../core/context7-client.mjs';
+import { installVersionGitHook, runVersionPreCommit, versioningStatus } from '../core/version-manager.mjs';
 import { rustInfo } from '../core/rust-accelerator.mjs';
 import { renderCartridge, validateCartridge, driftCartridge, snapshotCartridge } from '../core/gx-renderer.mjs';
 import { DEFAULT_EVAL_THRESHOLDS, compareEvaluationReports, defaultEvaluationScenario, runEvaluationBenchmark } from '../core/evaluation.mjs';
@@ -57,6 +58,7 @@ export async function main(args) {
   if (cmd === 'pipeline') return pipeline(sub, rest);
   if (cmd === 'guard') return guard(sub, rest);
   if (cmd === 'conflicts') return conflicts(sub, rest);
+  if (cmd === 'versioning') return versioning(sub, rest);
   if (cmd === 'reasoning') return reasoningCommand(tail);
   if (cmd === 'aliases') return aliases();
   if (cmd === 'setup') return setup(tail);
@@ -101,6 +103,7 @@ Usage:
   sks pipeline status|resume [--json]
   sks guard check [--json]
   sks conflicts check|prompt [--json]
+  sks versioning status|bump|pre-commit [--json]
   sks reasoning ["prompt"] [--json]
   sks aliases
   sks setup [--install-scope global|project] [--local-only] [--force] [--json]
@@ -161,10 +164,7 @@ async function postinstall() {
   const installRoot = path.resolve(process.env.INIT_CWD || process.cwd());
   const conflictScan = await scanHarnessConflicts(installRoot);
   if (conflictScan.hard_block) {
-    console.error('\nSneakoscope Codex install blocked.');
-    console.error(formatHarnessConflictReport(conflictScan));
-    console.error('\nRun the cleanup prompt above in Codex App with GPT-5.5 high mode, then rerun npm install.');
-    process.exitCode = 1;
+    await postinstallHarnessConflictNotice(conflictScan);
     return;
   }
   console.log('\nSneakoscope Codex installed.');
@@ -184,6 +184,40 @@ async function postinstall() {
   console.log('Project-only setup: `sks wizard` -> choose project, or `npx sks setup --install-scope project`.\n');
 }
 
+async function postinstallHarnessConflictNotice(conflictScan) {
+  console.log('\nSneakoscope Codex package installed, but SKS setup is blocked.');
+  console.log(formatHarnessConflictReport(conflictScan, { includePrompt: false }));
+  console.log('\nWhat this means: npm can finish installing the package, but `sks setup` and `sks doctor --fix` will refuse to activate SKS until the conflicting harness is removed with human approval.');
+  console.log('No files were removed by postinstall.');
+  console.log('Cleanup requires a human-approved Codex App session. Recommended model: GPT-5.5, reasoning: high.');
+  if (shouldAskPostinstallQuestion()) {
+    const answer = await askPostinstallQuestion('Show the cleanup prompt now? [y/N] ');
+    if (/^(y|yes|예|네|응)$/i.test(answer.trim())) {
+      console.log('\nCleanup prompt:\n');
+      console.log(llmHarnessCleanupPrompt(conflictScan));
+    } else {
+      console.log('Cleanup prompt skipped. You can print it later with: sks conflicts prompt');
+    }
+  } else {
+    console.log('Print the cleanup prompt later with: sks conflicts prompt');
+  }
+  console.log('After approved cleanup, rerun: sks setup && sks doctor --fix && sks selftest --mock\n');
+}
+
+function shouldAskPostinstallQuestion() {
+  if (process.env.SKS_POSTINSTALL_PROMPT === '1') return true;
+  return Boolean(input.isTTY && output.isTTY && process.env.CI !== 'true' && process.env.SKS_POSTINSTALL_NO_PROMPT !== '1');
+}
+
+async function askPostinstallQuestion(question) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
 async function ensureSksCommandDuringInstall(opts = {}) {
   if (process.env.SKS_SKIP_POSTINSTALL_SHIM === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_SHIM=1' };
   const pathEnv = opts.pathEnv ?? process.env.PATH ?? '';
@@ -566,6 +600,55 @@ async function conflicts(sub = 'check', args = []) {
   if (scan.conflicts.length) console.log(formatHarnessConflictReport(scan));
 }
 
+async function versioning(sub = 'status', args = []) {
+  const root = await projectRoot();
+  const action = sub || 'status';
+  if (action === 'status' || action === 'check') {
+    const status = await versioningStatus(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(status, null, 2));
+    console.log('SKS Project Versioning\n');
+    console.log(`Enabled:   ${status.enabled ? 'yes' : 'no'}${status.reason ? ` (${status.reason})` : ''}`);
+    console.log(`Version:   ${status.package_version || 'none'}`);
+    console.log(`Bump:      ${status.bump || 'patch'}`);
+    console.log(`Hook:      ${status.hook_installed ? 'installed' : 'missing'}${status.hook_path ? ` ${status.hook_path}` : ''}`);
+    console.log(`Last seen: ${status.last_version || 'none'}`);
+    if (!status.ok) console.log('Run: sks doctor --fix');
+    return;
+  }
+  if (action === 'hook' || action === 'install-hook') {
+    const res = await installVersionGitHook(root, await globalSksCommand());
+    if (flag(args, '--json')) return console.log(JSON.stringify(res, null, 2));
+    console.log(res.installed ? `Version hook installed: ${res.hook_path}` : `Version hook skipped: ${res.reason}`);
+    return;
+  }
+  if (action === 'bump') {
+    const res = await runVersionPreCommit(root, { force: true });
+    if (flag(args, '--json')) return console.log(JSON.stringify(res, null, 2));
+    if (!res.ok) {
+      console.error(`Version bump failed: ${res.reason || 'unknown'}`);
+      process.exitCode = 2;
+      return;
+    }
+    console.log(res.changed ? `Project version bumped: ${res.previous_version} -> ${res.version}` : `Project version already advanced: ${res.version}`);
+    console.log(`Staged: ${res.staged_files?.join(', ') || 'none'}`);
+    return;
+  }
+  if (action === 'pre-commit') {
+    const res = await runVersionPreCommit(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(res, null, 2));
+    if (!res.ok) {
+      console.error(`SKS versioning failed: ${res.reason || 'unknown'}`);
+      process.exitCode = 2;
+      return;
+    }
+    if (res.skipped) return;
+    console.log(res.changed ? `SKS versioning: ${res.previous_version} -> ${res.version}` : `SKS versioning: ${res.version} already unique`);
+    return;
+  }
+  console.error('Usage: sks versioning status|bump|pre-commit [--json]');
+  process.exitCode = 1;
+}
+
 async function reasoningCommand(args = []) {
   const prompt = promptOf(args);
   const route = routePrompt(prompt || '$SKS');
@@ -1008,14 +1091,34 @@ Print the LLM cleanup prompt:
   sks conflicts prompt
 
 Install behavior:
-  npm install/postinstall blocks when OMX, DCodex, or their global/repo-level traces are detected.
-  sks setup and sks doctor --fix also refuse to continue until a human approves cleanup.
+  npm install/postinstall prints a clean setup-blocked notice when OMX, DCodex, or their global/repo-level traces are detected.
+  npm can finish installing the package, but sks setup and sks doctor --fix refuse to continue until a human approves cleanup.
   If cleanup is denied, SKS cannot be installed in that environment.
 
 Cleanup operator:
   Use Codex App with GPT-5.5 high mode.
   Paste the prompt from sks conflicts prompt.
   The LLM must ask for explicit approval before deleting or moving conflicting harness artifacts.
+`,
+    versioning: `Project Versioning
+
+SKS installs a managed Git pre-commit hook during setup.
+Every commit in a package.json project gets a patch version bump in the same commit:
+  sks versioning status
+  sks versioning bump
+  sks versioning hook
+
+Commit behavior:
+  package.json version is bumped before Git writes the commit.
+  package-lock.json and npm-shrinkwrap.json are kept in sync when present.
+  The hook stages those version files automatically.
+
+Collision policy:
+  SKS uses a lock in the Git common directory, so multiple workers or worktrees cannot reuse the same version.
+  If another worker already used a version, the next commit bumps above the last seen version.
+
+Emergency bypass:
+  SKS_DISABLE_VERSIONING=1 git commit ...
 `,
     reasoning: `Reasoning Routing
 
@@ -1089,6 +1192,7 @@ async function setup(args) {
   const globalCommand = await globalSksCommand();
   const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand, localOnly });
   const install = await installStatus(root, installScope, { globalCommand });
+  const versioningInfo = await versioningStatus(root);
   const hooksPath = path.join(root, '.codex', 'hooks.json');
   const result = {
     root,
@@ -1103,6 +1207,7 @@ async function setup(args) {
       agents_rules: path.join(root, 'AGENTS.md')
     },
     created: res.created,
+    versioning: versioningInfo,
     local_only: localOnly,
     next: ['sks context7 check', 'sks selftest --mock', 'sks doctor', 'sks commands']
   };
@@ -1111,6 +1216,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)}`);
+  console.log(`Version:   ${versioningInfo.enabled ? (versioningInfo.hook_installed ? 'auto-bump enabled' : 'auto-bump hook missing') : 'not enabled'}${versioningInfo.package_version ? ` (${versioningInfo.package_version})` : ''}`);
   if (localOnly) console.log('Git:       local-only (.git/info/exclude; user AGENTS preserved, SKS managed block refreshed)');
   console.log(`Codex App: .codex/config.toml, .codex/hooks.json, .agents/skills, .codex/agents, .codex/SNEAKOSCOPE.md`);
   console.log(`Prompt:    skill-first pipeline, $DF fast design/content route, Context7 gate`);
@@ -1174,9 +1280,11 @@ async function doctor(args) {
   const context7Status = await checkContext7(root);
   const skillStatus = await checkRequiredSkills(root);
   const guardStatus = await harnessGuardStatus(root);
+  const versioningInfo = await versioningStatus(root);
   const codexApp = {
     config: { ok: await exists(path.join(root, '.codex', 'config.toml')) },
     hooks: { ok: await exists(path.join(root, '.codex', 'hooks.json')) },
+    versioning: versioningInfo,
     skills: skillStatus,
     agents: { ok: await exists(path.join(root, '.codex', 'agents')) },
     quick_reference: { ok: await exists(path.join(root, '.codex', 'SNEAKOSCOPE.md')) },
@@ -1196,6 +1304,7 @@ async function doctor(args) {
     sneakoscope: { ok: await exists(path.join(root, '.sneakoscope')) },
     context7: context7Status,
     harness_guard: guardStatus,
+    versioning: versioningInfo,
     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, '.agents', 'skills')) },
@@ -1205,7 +1314,7 @@ async function doctor(args) {
     },
     package: { bytes: pkgBytes, human: formatBytes(pkgBytes) }, storage
   };
-  result.ready = !result.harness_conflicts.hard_block && nodeOk && Boolean(codex.bin) && install.ok && result.sneakoscope.ok && result.context7.ok && result.harness_guard.ok && result.db_guard.ok && result.codex_app.ok && result.skills.ok;
+  result.ready = !result.harness_conflicts.hard_block && nodeOk && Boolean(codex.bin) && install.ok && result.sneakoscope.ok && result.context7.ok && result.harness_guard.ok && result.versioning.ok && result.db_guard.ok && result.codex_app.ok && result.skills.ok;
   if (result.harness_conflicts.hard_block) process.exitCode = 1;
   if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
   console.log('Sneakoscope Codex Doctor\n');
@@ -1220,6 +1329,7 @@ async function doctor(args) {
   console.log(`State:     ${result.sneakoscope.ok ? 'ok' : 'missing .sneakoscope'}`);
   console.log(`Context7:  ${result.context7.ok ? 'ok' : 'missing MCP config'} project=${result.context7.project.ok ? 'ok' : 'missing'} global=${result.context7.global.ok ? 'ok' : 'missing'}`);
   console.log(`Guard:     ${result.harness_guard.ok ? 'ok' : 'blocked'}${result.harness_guard.source_exception ? ' source-exception' : ''}`);
+  console.log(`Version:   ${result.versioning.ok ? 'ok' : 'missing'}${result.versioning.enabled ? ` ${result.versioning.package_version || ''}` : ` ${result.versioning.reason || 'disabled'}`}`);
   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 .agents/skills .codex/agents .codex/SNEAKOSCOPE.md`);
@@ -1233,6 +1343,7 @@ async function doctor(args) {
   if (result.harness_conflicts.hard_block) console.log(`\n${formatHarnessConflictReport(conflictScan)}`);
   if (!result.context7.ok) console.log('Context7 MCP missing. Run: sks context7 setup --scope project');
   if (!result.harness_guard.ok) console.log('Harness guard failed. Run: sks setup from a real terminal, then sks guard check.');
+  if (!result.versioning.ok) console.log('Versioning hook missing. Run: sks versioning hook, or sks doctor --fix.');
   if (!result.skills.ok) console.log(`Missing skills: ${result.skills.missing.join(', ')}. Run: sks setup`);
   if (!result.ready && !flag(args, '--fix')) console.log('Run: sks doctor --fix');
 }
@@ -1615,7 +1726,11 @@ async function selftest() {
   const conflictScan = await scanHarnessConflicts(conflictTmp, { home: path.join(conflictTmp, 'home') });
   if (!conflictScan.hard_block || !formatHarnessConflictReport(conflictScan).includes('GPT-5.5')) throw new Error('selftest failed: OMX conflict did not block with cleanup prompt');
   const postinstallConflict = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
-  if (postinstallConflict.code === 0 || !String(postinstallConflict.stderr || postinstallConflict.stdout).includes('install blocked')) throw new Error('selftest failed: postinstall did not block OMX conflict');
+  if (postinstallConflict.code !== 0) throw new Error('selftest failed: postinstall conflict notice should not make npm install fail');
+  const postinstallConflictOutput = String(`${postinstallConflict.stdout}\n${postinstallConflict.stderr}`);
+  if (!postinstallConflictOutput.includes('SKS setup is blocked') || postinstallConflictOutput.includes('Cleanup prompt:')) throw new Error('selftest failed: postinstall conflict notice did not stay informational');
+  const postinstallConflictPrompt = await runProcess(process.execPath, [path.join(packageRoot(), 'bin', 'sks.mjs'), 'postinstall'], { cwd: conflictTmp, input: 'y\n', env: { INIT_CWD: conflictTmp, HOME: path.join(conflictTmp, 'home'), SKS_SKIP_POSTINSTALL_SHIM: '1', SKS_SKIP_POSTINSTALL_CONTEXT7: '1', SKS_POSTINSTALL_PROMPT: '1' }, timeoutMs: 15000, maxOutputBytes: 128 * 1024 });
+  if (postinstallConflictPrompt.code !== 0 || !String(postinstallConflictPrompt.stdout || '').includes('Goal: completely remove the conflicting Codex harnesses')) throw new Error('selftest failed: interactive postinstall prompt did not print cleanup prompt');
   const guardBlocked = await checkHarnessModification(tmp, { tool_name: 'apply_patch', command: '*** Update File: .agents/skills/team/SKILL.md\n+tamper\n' });
   if (guardBlocked.action !== 'block') throw new Error('selftest failed: harness guard allowed skill tampering');
   const setupBlocked = await checkHarnessModification(tmp, { command: 'sks setup --force' });
@@ -1652,6 +1767,36 @@ 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 versionTmp = tmpdir();
+  await runProcess('git', ['init'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await runProcess('git', ['config', 'user.email', 'sks-selftest@example.invalid'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await runProcess('git', ['config', 'user.name', 'SKS Selftest'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await writeJsonAtomic(path.join(versionTmp, 'package.json'), { name: 'sks-version-selftest', version: '0.1.0' });
+  await writeJsonAtomic(path.join(versionTmp, 'package-lock.json'), { name: 'sks-version-selftest', version: '0.1.0', lockfileVersion: 3, packages: { '': { name: 'sks-version-selftest', version: '0.1.0' } } });
+  await runProcess('git', ['add', 'package.json', 'package-lock.json'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await runProcess('git', ['commit', '--no-verify', '-m', 'initial'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await writeTextAtomic(path.join(versionTmp, '.git', 'hooks', 'pre-commit'), '#!/bin/sh\nexit 0\n');
+  await initProject(versionTmp, {});
+  const versionStatus = await versioningStatus(versionTmp);
+  if (!versionStatus.ok || !versionStatus.enabled || !versionStatus.hook_installed) throw new Error('selftest failed: versioning hook not installed');
+  const versionHookText = await safeReadText(versionStatus.hook_path);
+  if (!versionHookText.includes('versioning pre-commit')) throw new Error('selftest failed: versioning hook command missing');
+  if (versionHookText.indexOf('versioning pre-commit') > versionHookText.indexOf('exit 0')) throw new Error('selftest failed: versioning hook was appended after an early exit');
+  await writeTextAtomic(path.join(versionTmp, 'README.md'), 'version selftest\n');
+  await runProcess('git', ['add', 'README.md'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  const firstVersionBump = await runVersionPreCommit(versionTmp);
+  if (!firstVersionBump.ok || firstVersionBump.version !== '0.1.1' || !firstVersionBump.changed) throw new Error('selftest failed: first version bump did not advance patch version');
+  const bumpedPackage = await readJson(path.join(versionTmp, 'package.json'));
+  const bumpedLock = await readJson(path.join(versionTmp, 'package-lock.json'));
+  if (bumpedPackage.version !== '0.1.1' || bumpedLock.version !== '0.1.1' || bumpedLock.packages[''].version !== '0.1.1') throw new Error('selftest failed: package lock versions not synced');
+  const firstCached = await runProcess('git', ['diff', '--cached', '--name-only'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  if (!firstCached.stdout.includes('package.json') || !firstCached.stdout.includes('package-lock.json')) throw new Error('selftest failed: version files not staged');
+  await runProcess('git', ['commit', '--no-verify', '-m', 'first versioned commit'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  await writeJsonAtomic(versionStatus.state_path, { schema_version: 1, last_version: '0.1.5', updated_at: nowIso(), pid: process.pid, changed: true });
+  await writeTextAtomic(path.join(versionTmp, 'CHANGELOG.md'), 'collision selftest\n');
+  await runProcess('git', ['add', 'CHANGELOG.md'], { cwd: versionTmp, timeoutMs: 15000, maxOutputBytes: 64 * 1024 });
+  const collisionBump = await runVersionPreCommit(versionTmp);
+  if (!collisionBump.ok || collisionBump.version !== '0.1.6') throw new Error('selftest failed: version collision state did not bump above last seen version');
   const localOnlyTmp = tmpdir();
   await ensureDir(path.join(localOnlyTmp, '.git'));
   await writeTextAtomic(path.join(localOnlyTmp, 'AGENTS.md'), 'existing local rules\n');

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

package/src/core/init.mjs

@@ -3,8 +3,9 @@ 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';
-import { writeHarnessGuardPolicy } from './harness-guard.mjs';
+import { isHarnessSourceProject, writeHarnessGuardPolicy } from './harness-guard.mjs';
 import { repairSksGeneratedArtifacts } from './harness-conflicts.mjs';
+import { installVersionGitHook } from './version-manager.mjs';
 import { DOLLAR_COMMANDS, DOLLAR_COMMAND_ALIASES, DOLLAR_SKILL_NAMES, RECOMMENDED_MCP_SERVERS, RECOMMENDED_SKILLS, context7ConfigToml, triwikiContextTracking, triwikiContextTrackingText } from './routes.mjs';
 
 export function normalizeInstallScope(scope = 'global') {
@@ -99,6 +100,10 @@ Sneakoscope Codex keeps runtime state bounded. Do not write large raw logs into
 
 Before any substantive work, SKS hooks check whether the installed SKS package is behind the latest published package. If an update is available, ask the user to choose between updating now and skipping the update for this conversation only. If the user skips, continue the current conversation without asking again, but check again in the next conversation. If the user accepts, update SKS, rerun setup/doctor, then continue the original task.
 
+## Project Versioning
+
+SKS manages the worker project's package version through a managed Git pre-commit hook. Every commit in a project with \`package.json\` gets a patch version bump in the same commit, with \`package-lock.json\` and \`npm-shrinkwrap.json\` kept in sync when present. The version guard uses a lock in the Git common directory so parallel workers or multiple worktrees do not reuse the same version. Check with \`sks versioning status\`; bypass only for exceptional maintenance with \`SKS_DISABLE_VERSIONING=1\`.
+
 ## Harness Self-Protection
 
 After setup, installed Sneakoscope harness control files are immutable to LLM tool edits. Do not edit \`.codex/hooks.json\`, \`.codex/config.toml\`, \`.codex/SNEAKOSCOPE.md\`, \`.agents/skills/\`, \`.codex/agents/\`, \`.sneakoscope/manifest.json\`, \`.sneakoscope/policy.json\`, \`.sneakoscope/db-safety.json\`, \`.sneakoscope/harness-guard.json\`, \`AGENTS.md\`, or \`node_modules/sneakoscope\` from the agent. SKS hooks block direct writes and SKS maintenance commands from LLM tool calls. The only automatic exception is the Sneakoscope engine source repository itself, detected by \`package.json\` name \`sneakoscope\` plus \`bin/sks.mjs\` and \`src/core/*\`.
@@ -253,7 +258,14 @@ export async function initProject(root, opts = {}) {
     git: {
       local_only: localOnly,
       exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
-      excluded_patterns: localExclude?.patterns || []
+      excluded_patterns: localExclude?.patterns || [],
+      versioning: {
+        enabled: true,
+        hook: 'pre-commit',
+        bump: 'patch',
+        lock: 'git-common-dir/sks-version.lock',
+        state: 'git-common-dir/sks-version-state.json'
+      }
     },
     database_safety: 'destructive_db_operations_denied_always',
     gx_renderer: 'deterministic_svg_html'
@@ -279,7 +291,23 @@ export async function initProject(root, opts = {}) {
         ...(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 || []
+        excluded_patterns: localExclude?.patterns || policy.git?.excluded_patterns || [],
+        versioning: {
+          ...(policy.git?.versioning || {}),
+          enabled: true,
+          hook: 'pre-commit',
+          bump: policy.git?.versioning?.bump || 'patch',
+          lock: 'git-common-dir/sks-version.lock',
+          state: 'git-common-dir/sks-version-state.json'
+        }
+      },
+      versioning: {
+        ...(policy.versioning || {}),
+        enabled: true,
+        bump: policy.versioning?.bump || 'patch',
+        trigger: 'git-pre-commit',
+        lock_scope: 'git-common-dir',
+        managed_files: ['package.json', 'package-lock.json', 'npm-shrinkwrap.json']
       },
       prompt_pipeline: {
         ...(policy.prompt_pipeline || {}),
@@ -329,7 +357,14 @@ export async function initProject(root, opts = {}) {
       git: {
         local_only: localOnly,
         exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
-        excluded_patterns: localExclude?.patterns || []
+        excluded_patterns: localExclude?.patterns || [],
+        versioning: {
+          enabled: true,
+          hook: 'pre-commit',
+          bump: 'patch',
+          lock: 'git-common-dir/sks-version.lock',
+          state: 'git-common-dir/sks-version-state.json'
+        }
       },
       retention: DEFAULT_RETENTION_POLICY,
       update_check: {
@@ -338,6 +373,14 @@ export async function initProject(root, opts = {}) {
         prompt_user_before_work: true,
         skip_scope: 'conversation_only'
       },
+      versioning: {
+        enabled: true,
+        bump: 'patch',
+        trigger: 'git-pre-commit',
+        lock_scope: 'git-common-dir',
+        managed_files: ['package.json', 'package-lock.json', 'npm-shrinkwrap.json'],
+        collision_policy: 'lock_then_bump_above_last_seen_version'
+      },
       honest_mode: {
         required_before_final: true,
         verify_goal_evidence_tests_gaps: true
@@ -463,6 +506,12 @@ export async function initProject(root, opts = {}) {
   created.push('.codex/agents/*');
   await writeHarnessGuardPolicy(root);
   created.push('.sneakoscope/harness-guard.json');
+  const versionHookCommand = await isHarnessSourceProject(root).catch(() => false)
+    ? 'node ./bin/sks.mjs'
+    : hookCommandPrefix;
+  const versionHook = await installVersionGitHook(root, versionHookCommand);
+  if (versionHook.installed) created.push('.git/hooks/pre-commit SKS version guard');
+  else created.push(`version guard skipped (${versionHook.reason})`);
   return { created };
 }
 

package/src/core/routes.mjs

@@ -1,4 +1,4 @@
-export const USAGE_TOPICS = 'install|setup|team|ralph|research|db|codex-app|df|dollar|context7|pipeline|reasoning|guard|conflicts|eval|gx|wiki';
+export const USAGE_TOPICS = 'install|setup|team|ralph|research|db|codex-app|df|dollar|context7|pipeline|reasoning|guard|conflicts|versioning|eval|gx|wiki';
 
 export const RECOMMENDED_MCP_SERVERS = [
   {
@@ -194,6 +194,7 @@ export const COMMAND_CATALOG = [
   { name: 'pipeline', usage: 'sks pipeline status|resume [--json]', description: 'Inspect the active skill-first route and its completion gates.' },
   { name: 'guard', usage: 'sks guard check [--json]', description: 'Check SKS harness self-protection lock, fingerprints, and source-repo exception state.' },
   { name: 'conflicts', usage: 'sks conflicts check|prompt [--json]', description: 'Detect other Codex harnesses such as OMX/DCodex and print the GPT-5.5 high cleanup prompt.' },
+  { name: 'versioning', usage: 'sks versioning status|bump|pre-commit [--json]', description: 'Manage automatic project version bumps on every commit with a shared Git lock.' },
   { name: 'aliases', usage: 'sks aliases', description: 'Show command aliases and npm binary names.' },
   { 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.' },

package/src/core/version-manager.mjs

@@ -0,0 +1,250 @@
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { ensureDir, exists, nowIso, readJson, runProcess, writeJsonAtomic, writeTextAtomic } from './fsx.mjs';
+
+const VERSION_HOOK_MARKER = 'Sneakoscope Codex Version Guard';
+const VERSION_STATE_FILE = 'sks-version-state.json';
+const DEFAULT_BUMP = 'patch';
+
+export async function installVersionGitHook(root, commandPrefix = 'sks') {
+  const git = await gitPaths(root);
+  if (!git.ok) return { ok: true, installed: false, reason: git.reason || 'not_git' };
+  const hookPath = git.hook_path;
+  const block = versionHookBlock(commandPrefix);
+  const current = await readFileMaybe(hookPath);
+  const next = mergeShellBlock(current, VERSION_HOOK_MARKER, block);
+  await ensureDir(path.dirname(hookPath));
+  await writeTextAtomic(hookPath, next);
+  await fsp.chmod(hookPath, 0o755).catch(() => {});
+  return { ok: true, installed: true, hook_path: hookPath };
+}
+
+export async function versioningStatus(root) {
+  const git = await gitPaths(root);
+  const packagePath = path.join(root, 'package.json');
+  const pkg = await readJson(packagePath, null);
+  const version = typeof pkg?.version === 'string' ? pkg.version : null;
+  if (!git.ok) return { ok: true, enabled: false, reason: git.reason || 'not_git', package_version: version };
+  const hookText = await readFileMaybe(git.hook_path);
+  const hookInstalled = hookText.includes(`BEGIN ${VERSION_HOOK_MARKER}`);
+  const policy = await versionPolicy(root);
+  const state = await readJson(path.join(git.common_dir, VERSION_STATE_FILE), {});
+  return {
+    ok: !policy.enabled || hookInstalled || !version,
+    enabled: Boolean(policy.enabled && version),
+    package_version: version,
+    bump: policy.bump,
+    hook_installed: hookInstalled,
+    hook_path: git.hook_path,
+    state_path: path.join(git.common_dir, VERSION_STATE_FILE),
+    last_version: state.last_version || null,
+    reason: version ? null : 'package_json_version_missing'
+  };
+}
+
+export async function runVersionPreCommit(root, opts = {}) {
+  if (process.env.SKS_DISABLE_VERSIONING === '1') return { ok: true, skipped: true, reason: 'SKS_DISABLE_VERSIONING=1' };
+  const policy = await versionPolicy(root);
+  if (!policy.enabled && !opts.force) return { ok: true, skipped: true, reason: 'disabled_by_policy' };
+  const pkgPath = path.join(root, 'package.json');
+  const pkg = await readJson(pkgPath, null);
+  if (!pkg?.version) return { ok: true, skipped: true, reason: 'package_json_version_missing' };
+  const git = await gitPaths(root);
+  if (!git.ok) return { ok: true, skipped: true, reason: git.reason || 'not_git' };
+  return withVersionLock(git.common_dir, async () => bumpProjectVersion(root, { ...opts, policy, git }));
+}
+
+export async function bumpProjectVersion(root, opts = {}) {
+  const policy = opts.policy || await versionPolicy(root);
+  const git = opts.git || await gitPaths(root);
+  const pkgPath = path.join(root, 'package.json');
+  const pkg = await readJson(pkgPath);
+  const current = parseSemver(pkg.version);
+  if (!current) return { ok: false, reason: `Unsupported package.json version: ${pkg.version}` };
+
+  const statePath = git.ok ? path.join(git.common_dir, VERSION_STATE_FILE) : null;
+  const state = statePath ? await readJson(statePath, {}) : {};
+  const headPkg = await gitJson(root, 'HEAD:package.json');
+  const headVersion = parseSemver(headPkg?.version);
+  const stateVersion = parseSemver(state.last_version);
+  const base = maxSemver([headVersion, stateVersion].filter(Boolean));
+  const manualAlreadyBumped = base && compareSemver(current, base) > 0;
+  const target = manualAlreadyBumped ? current : bumpSemver(base || current, policy.bump || DEFAULT_BUMP);
+  const changed = compareSemver(current, target) !== 0;
+
+  if (changed) {
+    pkg.version = formatSemver(target);
+    await writeJsonAtomic(pkgPath, pkg);
+  }
+  const synced = await syncPackageLockVersions(root, formatSemver(target));
+  const staged = await stageVersionFiles(root, [pkgPath, ...synced.files]);
+  if (!staged.ok) return { ok: false, reason: 'git_add_version_files_failed', stderr: staged.stderr };
+  if (statePath) {
+    await writeJsonAtomic(statePath, {
+      schema_version: 1,
+      last_version: formatSemver(target),
+      previous_version: pkg.version === formatSemver(target) && !changed ? formatSemver(current) : formatSemver(current),
+      updated_at: nowIso(),
+      pid: process.pid,
+      bump: policy.bump || DEFAULT_BUMP,
+      changed
+    });
+  }
+  await writeJsonAtomic(path.join(root, '.sneakoscope', 'version', 'last.json'), {
+    schema_version: 1,
+    version: formatSemver(target),
+    previous_version: formatSemver(current),
+    changed,
+    synced_files: synced.relative_files,
+    staged_files: staged.relative_files,
+    updated_at: nowIso()
+  }).catch(() => {});
+  return {
+    ok: true,
+    changed,
+    version: formatSemver(target),
+    previous_version: formatSemver(current),
+    synced_files: synced.relative_files,
+    staged_files: staged.relative_files,
+    lock_scope: git.common_dir
+  };
+}
+
+async function versionPolicy(root) {
+  const policy = await readJson(path.join(root, '.sneakoscope', 'policy.json'), {});
+  return {
+    enabled: policy.versioning?.enabled !== false,
+    bump: policy.versioning?.bump || DEFAULT_BUMP
+  };
+}
+
+async function gitPaths(root) {
+  const top = await git(root, ['rev-parse', '--show-toplevel']);
+  if (top.code !== 0) return { ok: false, reason: 'not_git' };
+  const common = await git(root, ['rev-parse', '--git-common-dir']);
+  const hook = await git(root, ['rev-parse', '--git-path', 'hooks/pre-commit']);
+  if (common.code !== 0 || hook.code !== 0) return { ok: false, reason: 'git_paths_unavailable' };
+  const topLevel = top.stdout.trim();
+  const commonDir = path.resolve(topLevel, common.stdout.trim());
+  const hookPath = path.resolve(topLevel, hook.stdout.trim());
+  return { ok: true, top_level: topLevel, common_dir: commonDir, hook_path: hookPath };
+}
+
+async function git(root, args, opts = {}) {
+  return runProcess('git', args, { cwd: root, timeoutMs: opts.timeoutMs || 15000, maxOutputBytes: opts.maxOutputBytes || 64 * 1024 });
+}
+
+async function gitJson(root, spec) {
+  const result = await git(root, ['show', spec], { maxOutputBytes: 256 * 1024 });
+  if (result.code !== 0) return null;
+  try { return JSON.parse(result.stdout); } catch { return null; }
+}
+
+async function withVersionLock(commonDir, fn) {
+  const lockDir = path.join(commonDir, 'sks-version.lock');
+  const started = Date.now();
+  let attempts = 0;
+  while (true) {
+    attempts += 1;
+    try {
+      await fsp.mkdir(lockDir);
+      await writeTextAtomic(path.join(lockDir, 'owner.json'), JSON.stringify({ pid: process.pid, started_at: nowIso() }, null, 2));
+      try {
+        const result = await fn();
+        return { ...result, lock_attempts: attempts };
+      } finally {
+        await fsp.rm(lockDir, { recursive: true, force: true }).catch(() => {});
+      }
+    } catch (err) {
+      if (err?.code !== 'EEXIST') throw err;
+      if (Date.now() - started > 15000) return { ok: false, reason: 'version_lock_timeout', lock_path: lockDir };
+      await sleep(150 + Math.min(750, attempts * 25));
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function syncPackageLockVersions(root, version) {
+  const files = [];
+  for (const rel of ['package-lock.json', 'npm-shrinkwrap.json']) {
+    const file = path.join(root, rel);
+    const json = await readJson(file, null);
+    if (!json) continue;
+    let changed = false;
+    if (json.version && json.version !== version) { json.version = version; changed = true; }
+    if (json.packages?.['']?.version && json.packages[''].version !== version) {
+      json.packages[''].version = version;
+      changed = true;
+    }
+    if (changed) {
+      await writeJsonAtomic(file, json);
+      files.push(file);
+    }
+  }
+  return { files, relative_files: files.map((file) => path.relative(root, file)) };
+}
+
+async function stageVersionFiles(root, files) {
+  const existing = [];
+  for (const file of files) if (await exists(file)) existing.push(path.relative(root, file));
+  if (!existing.length) return { ok: true, relative_files: [] };
+  const result = await git(root, ['add', '--', ...existing]);
+  return { ok: result.code === 0, relative_files: existing, stderr: result.stderr };
+}
+
+function parseSemver(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+function formatSemver(v) {
+  return `${v.major}.${v.minor}.${v.patch}`;
+}
+
+function compareSemver(a, b) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if ((a?.[key] || 0) > (b?.[key] || 0)) return 1;
+    if ((a?.[key] || 0) < (b?.[key] || 0)) return -1;
+  }
+  return 0;
+}
+
+function maxSemver(items) {
+  return items.reduce((max, item) => (!max || compareSemver(item, max) > 0 ? item : max), null);
+}
+
+function bumpSemver(v, bump = DEFAULT_BUMP) {
+  if (bump === 'major') return { major: v.major + 1, minor: 0, patch: 0 };
+  if (bump === 'minor') return { major: v.major, minor: v.minor + 1, patch: 0 };
+  return { major: v.major, minor: v.minor, patch: v.patch + 1 };
+}
+
+function versionHookBlock(commandPrefix) {
+  return `# SKS keeps package versions unique across worker commits.\n${commandPrefix} versioning pre-commit\nstatus=$?\nif [ $status -ne 0 ]; then\n  echo \"SKS versioning blocked commit. Run: sks versioning status\" >&2\n  exit $status\nfi`;
+}
+
+function mergeShellBlock(current, marker, block) {
+  const begin = `# BEGIN ${marker}`;
+  const end = `# END ${marker}`;
+  const managed = `${begin}\n${block.trim()}\n${end}\n`;
+  if (!current.trim()) return `#!/bin/sh\n${managed}`;
+  const withShebang = current.startsWith('#!') ? current : `#!/bin/sh\n${current}`;
+  const beginIdx = withShebang.indexOf(begin);
+  const endIdx = withShebang.indexOf(end);
+  if (beginIdx >= 0 && endIdx >= beginIdx) {
+    return `${withShebang.slice(0, beginIdx)}${managed}${withShebang.slice(endIdx + end.length).replace(/^\n/, '')}`;
+  }
+  const lines = withShebang.split('\n');
+  if (lines[0]?.startsWith('#!')) {
+    return `${lines[0]}\n${managed}${lines.slice(1).join('\n').replace(/^\n/, '')}`.replace(/\s*$/, '\n');
+  }
+  return `${managed}${withShebang.replace(/^\n/, '').replace(/\s*$/, '\n')}`;
+}
+
+async function readFileMaybe(file) {
+  try { return await fsp.readFile(file, 'utf8'); } catch { return ''; }
+}

package/docs/PERFORMANCE.md

@@ -1,83 +0,0 @@
-# Sneakoscope Codex performance and leak policy
-
-Sneakoscope Codex v0.6 is designed to keep runtime, package size, RAM, and storage bounded.
-
-## Speed
-
-- `codex exec` output is streamed to files and only a bounded tail is retained in memory.
-- Ralph cycles run under a timeout and bounded max cycles.
-- TriWiki claim selection uses bounded top-K selection plus RGBA/trig wiki anchors instead of sorting unbounded context into prompts.
-- GX visual context renders deterministic SVG/HTML from JSON sources, avoiding external image-generation latency, cost, and nondeterminism. Rendered nodes expose the same RGBA wiki-coordinate anchors used by TriWiki.
-- `sks gc` runs after Ralph cycles by default.
-
-## Evaluation metrics
-
-`sks eval run` creates a deterministic JSON report in `.sneakoscope/reports/` unless `--no-save` is used. The built-in scenario compares an uncompressed all-claims baseline with a TriWiki compressed context capsule.
-
-Tracked metrics:
-
-- `estimated_tokens`: deterministic chars/4 prompt-size estimate for local regression tracking
-- `token_savings_pct`: prompt-size reduction versus baseline
-- `accuracy_proxy`: evidence-weighted context-selection quality score
-- `required_recall`: required claim coverage
-- `relevance_precision`: selected required claims divided by selected claims
-- `support_ratio`: selected claims that are supported or weakly supported
-- `unsupported_critical_selected`: critical/high unsupported claims that survived compression
-- `context_build_ms_per_run`: local context construction runtime
-- `meaningful_improvement`: true only when token savings, accuracy delta, recall, unsupported-critical filtering, and runtime thresholds pass
-
-Default meaningful-improvement thresholds are intentionally explicit: at least 25% token savings, at least +0.03 accuracy-proxy delta, at least 0.95 required recall, zero unsupported critical claims selected, and candidate context construction under 25 ms per run. `sks eval compare --baseline old.json --candidate new.json` compares saved reports across implementations.
-
-The accuracy metric is not a live model task score. It is a deterministic proxy for whether the context handed to a model is smaller, better supported, and less contaminated by unsupported critical claims.
-
-## LLM Wiki coordinate continuity
-
-TriWiki does not treat compression as permanent deletion. The visible context pack includes selected claim text plus a compact LLM Wiki coordinate index:
-
-```text
-R channel -> domain angle
-G channel -> layer radius via sin()
-B channel -> phase angle
-A channel -> concentration/confidence
-```
-
-Each anchor stores id, RGBA key, `[domain, layer, phase, concentration]`, source path, status/risk, and a text hash. This keeps non-selected claims hydratable across turns while keeping raw Q0 logs and large Q1 evidence out of the prompt until verification needs them.
-
-## Package size
-
-- The npm package has zero runtime dependencies.
-- `@openai/codex` is no longer bundled. Users install Codex separately or set `SKS_CODEX_BIN`.
-- Optional Rust source is in `crates/` for the Git repo, but is excluded from the npm package by the `files` allowlist.
-- GX rendering uses only built-in Node.js APIs and ships as source in the npm package.
-- `npm run sizecheck` enforces package limits during `release:check`, `publish:dry`, and publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
-
-## Memory leaks
-
-- Child process stdout/stderr never accumulate unbounded strings.
-- Large outputs are written to log files and returned as tails.
-- Recursive file walking has file/depth caps.
-- No long-lived global caches are used.
-
-## Storage leaks
-
-- `.sneakoscope/policy.json` controls retention.
-- Old missions, old Ralph cycle directories, arenas, temp files, and oversized JSONL logs are removed or rotated by `sks gc`.
-- `sks stats` reports package/state size.
-
-## Rust decision
-
-Rust is useful for CPU-heavy long-running kernels, but not for the default npm package yet: native binaries increase package size and create OS/architecture install failure modes. Sneakoscope Codex therefore ships a zero-dependency Node runtime by default and includes an optional zero-dependency Rust helper source at `crates/sks-core` for future builds or users who want to compile locally.
-
-## Database safety resource policy
-
-Sneakoscope Codex v0.3 adds a DB Safety Guard without adding runtime dependencies. It scans hook payloads and CLI commands with bounded string traversal and blocks high-risk database operations before Codex can execute them.
-
-Blocked classes include destructive SQL, direct remote SQL mutation, `supabase db reset`, `supabase db push`, migration history repair/squash, and project/branch destructive commands. The guard is intentionally conservative: when unsure, it blocks or warns rather than allowing a potentially destructive database operation.
-
-## GX visual context policy
-
-Sneakoscope Codex v0.4 replaces model-rendered visual cartridges with deterministic code-rendered context sheets. `vgraph.json` and `beta.json` are the inputs, `render.svg` and `render.html` are reproducible outputs, and `drift.json` records whether the rendered source hash still matches the current graph.
-
-This keeps visual context cheap to regenerate, diffable in normal tooling, and safe to validate during npm packaging without network calls or model access.
-
-GX snapshots include `wiki_coordinates`, and `render.svg` nodes include `data-wiki-rgba` and `data-wiki-coord` attributes. This makes the visual context sheet and LLM Wiki pack share one deterministic coordinate system.

package/docs/assets/sneakoscope-codex-logo.svg

@@ -1,51 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
-  <title id="title">Sneakoscope Codex logo</title>
-  <desc id="desc">A brass magical danger-sensing lens with a red core, orbiting rings, and SKS initials.</desc>
-  <defs>
-    <radialGradient id="lens" cx="50%" cy="42%" r="58%">
-      <stop offset="0%" stop-color="#fff4c2"/>
-      <stop offset="42%" stop-color="#f0b54f"/>
-      <stop offset="100%" stop-color="#7b241f"/>
-    </radialGradient>
-    <linearGradient id="brass" x1="92" x2="420" y1="80" y2="432">
-      <stop offset="0%" stop-color="#ffe28a"/>
-      <stop offset="46%" stop-color="#c9872e"/>
-      <stop offset="100%" stop-color="#6c3218"/>
-    </linearGradient>
-    <linearGradient id="ink" x1="160" x2="352" y1="154" y2="358">
-      <stop offset="0%" stop-color="#311018"/>
-      <stop offset="100%" stop-color="#15070b"/>
-    </linearGradient>
-    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
-      <feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#12070a" flood-opacity=".28"/>
-    </filter>
-  </defs>
-
-  <rect width="512" height="512" rx="108" fill="#16080d"/>
-  <path fill="#241016" d="M64 346c61 66 122 96 193 96 72 0 138-34 197-101v106c0 21-17 38-38 38H102c-21 0-38-17-38-38V346Z" opacity=".65"/>
-
-  <g filter="url(#shadow)">
-    <path fill="none" stroke="url(#brass)" stroke-width="16" stroke-linecap="round" d="M99 256c41-82 95-123 158-123 62 0 115 41 156 123-41 82-94 123-156 123-63 0-117-41-158-123Z"/>
-    <path fill="none" stroke="#f4c56a" stroke-width="5" stroke-linecap="round" d="M126 256c34-61 78-92 131-92 52 0 96 31 130 92-34 61-78 92-130 92-53 0-97-31-131-92Z" opacity=".86"/>
-
-    <circle cx="256" cy="256" r="93" fill="url(#brass)"/>
-    <circle cx="256" cy="256" r="74" fill="url(#ink)"/>
-    <circle cx="256" cy="256" r="56" fill="url(#lens)"/>
-    <circle cx="237" cy="236" r="16" fill="#fff8d8" opacity=".82"/>
-    <circle cx="283" cy="282" r="9" fill="#5b1017" opacity=".75"/>
-
-    <path fill="#fff0a4" d="M256 176l14 57 55-18-42 39 43 38-56-16-14 57-14-57-56 16 43-38-42-39 55 18 14-57Z"/>
-    <circle cx="256" cy="256" r="17" fill="#7b0f17"/>
-
-    <path fill="none" stroke="#f6d37c" stroke-width="11" stroke-linecap="round" d="M256 75v36M256 401v36M75 256h36M401 256h36"/>
-    <path fill="none" stroke="#b86232" stroke-width="8" stroke-linecap="round" d="M133 132l26 26M353 354l26 26M379 132l-26 26M159 354l-26 26"/>
-
-    <g fill="#fff0bc">
-      <circle cx="127" cy="113" r="7"/>
-      <circle cx="385" cy="113" r="7"/>
-      <circle cx="127" cy="399" r="7"/>
-      <circle cx="385" cy="399" r="7"/>
-    </g>
-  </g>
-
-</svg>