@dzhechkov/keysarium 1.7.15 → 1.7.19

package/src/cli.js

@@ -10,7 +10,7 @@ function showBanner() {
   console.log('');
   console.log(cyan('╔══════════════════════════════════════════════════════╗'));
   console.log(cyan('║') + bold('        \uD83D\uDD2C DZ-KEYSARIUM — AI Research Toolkit        ') + cyan('║'));
-  console.log(cyan('║') + '     Full 7-phase pipeline for Claude Code           ' + cyan('║'));
+  console.log(cyan('║') + '        Full 7-phase research pipeline               ' + cyan('║'));
   console.log(cyan('╚══════════════════════════════════════════════════════╝'));
   console.log('');
 }
@@ -40,6 +40,8 @@ function showHelp() {
   console.log('  ' + yellow('--minimal') + '    Install only .claude/ directory (skills, commands, rules)');
   console.log('  ' + yellow('--force') + '      Overwrite existing files without prompting');
   console.log('  ' + yellow('--with-docs') + '  Include docs/ directory');
+  console.log('  ' + yellow('--target') + '     Install for claude (default) or codex');
+  console.log('  ' + yellow('--project') + '    Project directory (default: current directory)');
   console.log('  ' + yellow('--dry-run') + '    Show what would be done without making changes');
   console.log('  ' + yellow('--help, -h') + '   Show this help message');
   console.log('  ' + yellow('--version, -v') + ' Show version number');
@@ -47,6 +49,7 @@ function showHelp() {
   console.log(bold('Examples:'));
   console.log(dim('  $ ') + 'npx @dzhechkov/keysarium init');
   console.log(dim('  $ ') + 'npx @dzhechkov/keysarium init --minimal --force');
+  console.log(dim('  $ ') + 'npx @dzhechkov/keysarium init --target codex --project ./my-case');
   console.log(dim('  $ ') + 'npx @dzhechkov/keysarium update --dry-run');
   console.log(dim('  $ ') + 'npx @dzhechkov/keysarium doctor');
   console.log('');
@@ -64,11 +67,14 @@ function parseArgs(argv) {
     withDocs: false,
     dryRun: false,
     targetDir: process.cwd(),
+    target: 'claude',
+    targetSpecified: false,
   };
 
   let command = null;
 
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
     switch (arg) {
       case '--minimal':
         flags.minimal = true;
@@ -82,6 +88,25 @@ function parseArgs(argv) {
       case '--dry-run':
         flags.dryRun = true;
         break;
+      case '--target': {
+        const value = args[++index];
+        if (value !== 'claude' && value !== 'codex') {
+          error('--target must be claude or codex');
+          process.exit(1);
+        }
+        flags.target = value;
+        flags.targetSpecified = true;
+        break;
+      }
+      case '--project': {
+        const value = args[++index];
+        if (!value || value.startsWith('-')) {
+          error('--project requires a directory path');
+          process.exit(1);
+        }
+        flags.targetDir = path.resolve(value);
+        break;
+      }
       case '--help':
       case '-h':
         command = 'help';
@@ -132,6 +157,11 @@ function main() {
 
   // Route to command handlers
   const resolvedCommand = command || 'init';
+  if (flags.targetSpecified && resolvedCommand !== 'init') {
+    error('--target is supported only by init; update and doctor use the installation manifest');
+    process.exitCode = 1;
+    return;
+  }
 
   switch (resolvedCommand) {
     case 'init':

package/src/commands/doctor.js

@@ -293,6 +293,28 @@ function checkSettingsValid(targetDir) {
   });
 }
 
+function checkCodexEntrypoint(targetDir) {
+  return check('Codex entrypoint', () => {
+    const entry = path.join(targetDir, '.agents', 'skills', 'casarium', 'SKILL.md');
+    const command = path.join(targetDir, '.claude', 'commands', 'casarium.md');
+    const shards = path.join(targetDir, '.claude', 'shards');
+    const missing = [entry, command, shards].filter((item) => !fileExists(item));
+    if (missing.length > 0) {
+      return { passed: false, detail: `Missing ${missing.map((item) => path.relative(targetDir, item)).join(', ')}`,
+        fix: 'Run keysarium update to restore the installed Codex entrypoint.' };
+    }
+    const body = fs.readFileSync(entry, 'utf8');
+    const frontmatter = body.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    if (!frontmatter || !/^name:\s*casarium\s*$/m.test(frontmatter[1])
+      || !/^description:\s*\S.+$/m.test(frontmatter[1])
+      || !body.includes('.claude/commands/casarium.md')) {
+      return { passed: false, detail: 'SKILL.md lacks Codex discovery metadata or the canonical command reference',
+        fix: 'Run keysarium update to restore the Codex entrypoint.' };
+    }
+    return { passed: true, detail: 'Project skill and canonical pipeline references present' };
+  });
+}
+
 /**
  * Check 8: researches/ directory exists.
  */
@@ -372,7 +394,9 @@ async function run(options) {
     checkRulesPresent(targetDir),
     checkShardsPresent(targetDir),
     checkAgentsPresent(targetDir),
-    checkSettingsValid(targetDir),
+    manifest.components?.includes('codex_entry')
+      ? checkCodexEntrypoint(targetDir)
+      : checkSettingsValid(targetDir),
     checkResearchDir(targetDir),
   ];
 

package/src/commands/init.js

@@ -8,6 +8,7 @@ const {
   copyDirRecursive, copyDirTracked, fileExists, readJSON,
   ensureDir, getRelativePaths,
   createManifest, writeManifest, getTemplatesDir,
+  hashFile,
   COMPONENTS, MANIFEST_FILE,
 } = require('../utils');
 
@@ -22,8 +23,10 @@ const {
  *   --with-docs: add docs group
  */
 function resolveComponents(options) {
-  const { minimal, withDocs } = options;
-  const coreKeys = ['skills', 'commands', 'rules', 'shards', 'agents', 'hooks', 'claude_md', 'harvest'];
+  const { minimal, withDocs, target } = options;
+  const coreKeys = ['skills', 'commands', 'rules', 'shards', 'agents', 'claude_md', 'harvest'];
+  if (target === 'codex') coreKeys.push('codex_entry');
+  else coreKeys.push('hooks');
   const keys = [...coreKeys];
 
   if (!minimal) {
@@ -81,9 +84,10 @@ function installComponent(comp, templatesDir, targetDir, force) {
  * @param {boolean} options.withDocs  — Include docs/ directory
  * @param {boolean} options.dryRun    — Preview without writing anything
  * @param {string}  options.targetDir — Destination project root
+ * @param {string}  options.target    — claude (default) or codex
  */
 async function run(options) {
-  const { force, dryRun, targetDir } = options;
+  const { force, dryRun, targetDir, target = 'claude' } = options;
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Check for existing installation ──────────────────────────────────
@@ -93,9 +97,25 @@ async function run(options) {
       info(`Run ${cyan('npx @dzhechkov/keysarium update')} to update, or use ${yellow('--force')} to overwrite.`);
       process.exit(1);
     }
+    const existing = readJSON(manifestPath);
+    if (!existing || !Array.isArray(existing.components)) {
+      logError('Existing .keysarium.json is invalid; refusing to overwrite its ownership record.');
+      process.exit(1);
+    }
+    const existingTarget = existing.components.includes('codex_entry') ? 'codex' : 'claude';
+    if (existingTarget !== target) {
+      logError(`Cannot switch an installed ${existingTarget} toolkit to ${target} with --force. Remove it first, then init for the new target.`);
+      process.exit(1);
+    }
     warn('Existing installation found — overwriting (--force).');
   }
 
+  const codexEntryPath = path.join(targetDir, '.agents', 'skills', 'casarium', 'SKILL.md');
+  if (target === 'codex' && fileExists(codexEntryPath) && !force) {
+    logError('A project skill named casarium already exists. Use --force only if it may be replaced.');
+    process.exit(1);
+  }
+
   // ── b) Determine components ─────────────────────────────────────────────
   const componentKeys = resolveComponents(options);
   const templatesDir = getTemplatesDir();
@@ -103,6 +123,7 @@ async function run(options) {
   // ── c) Show plan ────────────────────────────────────────────────────────
   console.log('');
   info(bold('Installation plan:'));
+  info(`Target: ${target}; project: ${targetDir}`);
   console.log('');
 
   for (const key of componentKeys) {
@@ -145,6 +166,15 @@ async function run(options) {
   const version = pkg ? pkg.version : '0.0.0';
 
   const manifest = createManifest(version, componentKeys, installedFiles.sort());
+  // Only claim a baseline for the planner when the installed bytes equal the template.
+  // A pre-existing user file preserved by init must not be adopted as our version.
+  const plannerRel = path.join('.claude', 'agents', 'code-goal-planner.md');
+  const installedPlanner = path.join(targetDir, plannerRel);
+  const templatePlanner = path.join(templatesDir, plannerRel);
+  if (fileExists(installedPlanner) && fileExists(templatePlanner)
+      && hashFile(installedPlanner) === hashFile(templatePlanner)) {
+    manifest.templateHashes = { [plannerRel]: hashFile(templatePlanner) };
+  }
   writeManifest(targetDir, manifest);
   info('Created .keysarium.json manifest');
 
@@ -161,16 +191,30 @@ async function run(options) {
 
   console.log('');
   console.log(bold('Next steps:'));
-  console.log(`  1. Open ${cyan('Claude Code')} in this directory`);
-  console.log(`  2. Run ${cyan('/casarium [your case description]')}`);
-  console.log(`  3. Follow the 7-phase pipeline`);
-  console.log('');
-  console.log(bold('Available commands:'));
-  console.log(`  ${cyan('/casarium')}          ${dim('\u2014 Full pipeline')}`);
-  console.log(`  ${cyan('/new-research')}      ${dim('\u2014 New research')}`);
-  console.log(`  ${cyan('/parallel-research')} ${dim('\u2014 Multiple cases in parallel')}`);
-  console.log(`  ${cyan('/harvest')}           ${dim('\u2014 Extract knowledge')}`);
+  if (target === 'codex') {
+    console.log(`  1. Open ${cyan('Codex')} in ${targetDir}`);
+    console.log(`  2. Invoke ${cyan('$casarium [your case description]')}`);
+    console.log(`  3. Confirm each phase checkpoint and select a CJM variant`);
+    console.log('');
+    console.log(bold('Codex integration status:'));
+    console.log('  Bundled workflow skills: installed under .claude/skills/ as phase references');
+    console.log('  Full pipeline entrypoint: installed at .agents/skills/casarium/SKILL.md');
+    console.log('  Codex hooks and MCP integrations: not installed');
+    console.log('  Claude settings/hooks: not installed for this target');
+  } else {
+    console.log(`  1. Open ${cyan('Claude Code')} in this directory`);
+    console.log(`  2. Run ${cyan('/casarium [your case description]')}`);
+    console.log(`  3. Follow the 7-phase pipeline`);
+  }
   console.log('');
+  if (target === 'claude') {
+    console.log(bold('Available commands:'));
+    console.log(`  ${cyan('/casarium')}          ${dim('\u2014 Full pipeline')}`);
+    console.log(`  ${cyan('/new-research')}      ${dim('\u2014 New research')}`);
+    console.log(`  ${cyan('/parallel-research')} ${dim('\u2014 Multiple cases in parallel')}`);
+    console.log(`  ${cyan('/harvest')}           ${dim('\u2014 Extract knowledge')}`);
+    console.log('');
+  }
 
   process.exit(0);
 }

package/src/commands/update.js

@@ -7,6 +7,7 @@ const {
   info, success, warn, error: logError, step,
   copyDirRecursive, fileExists, readJSON,
   ensureDir, getRelativePaths, diffFiles,
+  hashFile,
   readManifest, writeManifest, getTemplatesDir,
   COMPONENTS, MANIFEST_FILE,
 } = require('../utils');
@@ -20,11 +21,11 @@ const {
  *
  * @param {object} options
  * @param {boolean} options.dryRun    — Preview without writing anything
- * @param {boolean} options.force     — Passed through (unused here)
+ * @param {boolean} options.force     — Back up and replace a locally edited planner agent
  * @param {string}  options.targetDir — Destination project root
  */
 async function run(options) {
-  const { dryRun, targetDir } = options;
+  const { dryRun, force, targetDir } = options;
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Read existing manifest ───────────────────────────────────────────
@@ -60,7 +61,11 @@ async function run(options) {
   let totalAdded = 0;
   let totalModified = 0;
   let totalUnchanged = 0;
+  let preservedPlanner = false;
   const filesToCopy = []; // { src, dest, status, relPath }
+  const plannerRel = path.join('.claude', 'agents', 'code-goal-planner.md');
+  // The unmodified wrapper shipped before the full agent was introduced.
+  const legacyPlannerHash = 'fd6faca31bacfa3c70c0ff2a8ba152957d952b8590b4df0934ffd19af5078592';
 
   for (const key of installedKeys) {
     const comp = COMPONENTS[key];
@@ -107,11 +112,24 @@ async function run(options) {
       }
 
       for (const rel of diff.modified) {
+        const relPath = path.join(comp.src, rel);
+        let backup = false;
+        if (relPath === plannerRel) {
+          const currentHash = hashFile(path.join(destBase, rel));
+          const baseline = manifest.templateHashes?.[plannerRel];
+          const clean = currentHash === baseline || (!baseline && currentHash === legacyPlannerHash);
+          if (!clean && !force) {
+            preservedPlanner = true;
+            continue;
+          }
+          backup = !clean;
+        }
         filesToCopy.push({
           src: path.join(srcBase, rel),
           dest: path.join(destBase, rel),
           status: 'modified',
-          relPath: path.join(comp.src, rel),
+          relPath,
+          backup,
         });
         totalModified++;
       }
@@ -125,6 +143,7 @@ async function run(options) {
   console.log(`  ${green('+')} ${totalAdded} file(s) to add`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) to update`);
   console.log(`  ${dim('=')} ${totalUnchanged} file(s) unchanged`);
+  if (preservedPlanner) warn(`Local edit preserved: ${plannerRel}. Use --force to back up and replace it.`);
   console.log('');
 
   if (totalAdded === 0 && totalModified === 0) {
@@ -137,6 +156,7 @@ async function run(options) {
     for (const f of filesToCopy) {
       const marker = f.status === 'added' ? green('+ ADD') : yellow('~ MOD');
       console.log(`  ${marker}  ${f.relPath}`);
+      if (f.backup) console.log(`         backup: ${f.relPath}.bak`);
     }
     console.log('');
     warn('Dry run — no files were written.');
@@ -150,6 +170,7 @@ async function run(options) {
     step(i + 1, filesToCopy.length, `${label} ${f.relPath}`);
 
     ensureDir(path.dirname(f.dest));
+    if (f.backup) fs.copyFileSync(f.dest, `${f.dest}.bak`);
     fs.copyFileSync(f.src, f.dest);
   }
 
@@ -176,6 +197,12 @@ async function run(options) {
   manifest.version = newVersion;
   manifest.updatedAt = new Date().toISOString();
   manifest.files = allFiles.sort();
+  const installedPlanner = path.join(targetDir, plannerRel);
+  const templatePlanner = path.join(templatesDir, plannerRel);
+  if (fileExists(installedPlanner) && fileExists(templatePlanner)
+      && hashFile(installedPlanner) === hashFile(templatePlanner)) {
+    manifest.templateHashes = { ...manifest.templateHashes, [plannerRel]: hashFile(templatePlanner) };
+  }
 
   writeManifest(targetDir, manifest);
   info('Updated .keysarium.json manifest');

package/src/utils.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { createHash } = require('node:crypto');
 
 // ===========================================================================
 // Colors — ANSI escape codes (zero dependencies)
@@ -36,6 +37,10 @@ function step(n, total, msg) {
   console.log(cyan(`[${n}/${total}]`) + ' ' + msg);
 }
 
+function hashFile(file) {
+  return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
 // ===========================================================================
 // File operations — all synchronous, Node.js built-ins only
 // ===========================================================================
@@ -311,6 +316,7 @@ const COMPONENT_SPECS = {
   docs:      { src: 'docs',                  name: 'Documentation',    unit: 'guides',         countMode: 'files', group: 'docs' },
   claude_md: { src: 'CLAUDE.md',             name: 'Master instructions', group: 'core', isFile: true },
   harvest:   { src: 'TOOLKIT_HARVEST.md',    name: 'Knowledge harvest tracker', group: 'core', isFile: true },
+  codex_entry: { src: '.agents/skills/casarium', name: 'Codex pipeline entrypoint', unit: 'entrypoint', countMode: 'files', group: 'codex' },
 };
 
 /**
@@ -370,6 +376,7 @@ module.exports = {
   warn,
   error,
   step,
+  hashFile,
 
   // File operations
   copyDirRecursive,

package/templates/.agents/skills/casarium/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: casarium
+description: Run the installed Keysarium seven-phase case research pipeline in Codex, with phase artifacts and user checkpoints. Use when the user invokes $casarium or asks to work through a Keysarium case.
+---
+
+# Casarium in Codex
+
+This project contains the complete Keysarium workflow. Start by reading
+`.claude/commands/casarium.md`; it is the source of truth for phase order, outputs and
+checkpoints. Treat its `$ARGUMENTS` as the user's request after `$casarium`. If the case is
+missing, ask for it.
+
+For each phase, read only its `.claude/shards/phase-*.shard.md` and the skill files it names
+under `.claude/skills/`. Read `.claude/rules/checkpoint-protocol.md` and
+`.claude/rules/research-quality.md` when reaching their gates. Create phase artifacts under
+`researches/<case-name>/` as the phase runs. Show the checkpoint and wait for the user's
+confirmation before advancing. Phase 2.5 requires an explicit CJM choice; preserve that
+choice in later phases. A failed research gate cannot emit a success promise.
+
+The `.claude/` files are workflow references in Codex. Claude slash commands, Agent tool
+calls, hook settings and model names inside them are not Codex commands or installed Codex
+integrations. Use available Codex tools for the work and state any unavailable capability;
+do not claim that a named Claude agent or hook ran. Parallel work is optional when the host
+supports it. The research mode requirements still apply to every worker.
+
+If the case asks for AI Factory mapping, read
+`.claude/shards/phase-ai-factory.shard.md` and its referenced skill before Phase 0. Otherwise
+leave that branch inactive. The project-local `$casarium` skill is the Codex entrypoint;
+`/casarium` remains the Claude Code entrypoint.