@dzhechkov/keysarium 1.5.1 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, reward learning, and Cloud.ru AI Factory mapping (--ai-factory flag)",
   "main": "src/cli.js",
   "bin": {
@@ -50,4 +50,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/cli.js

@@ -91,8 +91,17 @@ function parseArgs(argv) {
         command = 'version';
         break;
       default:
-        if (!arg.startsWith('-') && command === null) {
+        if (arg.startsWith('-')) {
+          // Reject unknown options loudly — a typo like --dry-rum or --froce must
+          // never silently downgrade behavior (real install instead of dry-run, or
+          // an unguarded destructive command).
+          error(`Unknown option: ${arg}`);
+          process.exit(1);
+        } else if (command === null) {
           command = arg;
+        } else {
+          error(`Unexpected argument: ${arg}`);
+          process.exit(1);
         }
         break;
     }

package/src/commands/init.js

@@ -5,7 +5,7 @@ const path = require('path');
 const {
   green, yellow, cyan, bold, dim,
   info, success, warn, error: logError, step,
-  copyDirRecursive, fileExists, readJSON,
+  copyDirRecursive, copyDirTracked, fileExists, readJSON,
   ensureDir, getRelativePaths,
   createManifest, writeManifest, getTemplatesDir,
   COMPONENTS, MANIFEST_FILE,
@@ -41,7 +41,7 @@ function resolveComponents(options) {
  * Copy a single component from templates to the target directory.
  * Returns array of relative file paths that were installed.
  */
-function installComponent(comp, templatesDir, targetDir) {
+function installComponent(comp, templatesDir, targetDir, force) {
   const src = path.join(templatesDir, comp.src);
   const dest = path.join(targetDir, comp.src);
 
@@ -51,13 +51,21 @@ function installComponent(comp, templatesDir, targetDir) {
   }
 
   if (comp.isFile) {
+    if (fileExists(dest) && !force) {
+      // Preserve a user-modified file (e.g. their own CLAUDE.md / settings.json)
+      // when re-installing without --force. It is still manifest-tracked because
+      // it originates from the template.
+      return [comp.src];
+    }
     ensureDir(path.dirname(dest));
     fs.copyFileSync(src, dest);
     return [comp.src];
   }
 
-  copyDirRecursive(src, dest);
-  return getRelativePaths(dest).map((rel) => path.join(comp.src, rel));
+  // Track files via the TEMPLATE source — never a scan of the destination —
+  // so user-created files under dest are neither recorded nor (later) removed.
+  const { copied, skipped } = copyDirTracked(src, dest, force);
+  return [...copied, ...skipped].map((rel) => path.join(comp.src, rel));
 }
 
 // ---------------------------------------------------------------------------
@@ -118,7 +126,7 @@ async function run(options) {
     const comp = COMPONENTS[key];
     step(i + 1, totalComponents, `Installing ${comp.label}...`);
 
-    const files = installComponent(comp, templatesDir, targetDir);
+    const files = installComponent(comp, templatesDir, targetDir, force);
     installedFiles.push(...files);
   }
 

package/src/commands/update.js

@@ -159,12 +159,16 @@ async function run(options) {
     const comp = COMPONENTS[key];
     if (!comp) continue;
     const destPath = path.join(targetDir, comp.src);
+    const srcPath = path.join(templatesDir, comp.src);
     if (comp.isFile) {
       if (fileExists(destPath)) {
         allFiles.push(comp.src);
       }
     } else if (fileExists(destPath)) {
-      const paths = getRelativePaths(destPath);
+      // Record files from the TEMPLATE source, not a scan of the destination —
+      // otherwise user-created files in dest get adopted into the manifest and
+      // a later `remove` would delete them.
+      const paths = getRelativePaths(fileExists(srcPath) ? srcPath : destPath);
       allFiles.push(...paths.map((rel) => path.join(comp.src, rel)));
     }
   }

package/src/utils.js

@@ -64,6 +64,39 @@ function copyDirRecursive(src, dest) {
   }
 }
 
+/**
+ * Copy from a TEMPLATE source into dest, tracking which files were written.
+ * Walks the SOURCE tree (never the destination), so only template-originated
+ * files are ever recorded — a user-created file in dest with no template
+ * counterpart is never touched and never returned (prevents `remove` from
+ * deleting user data). When `force` is false, a pre-existing destination file
+ * is PRESERVED (skipped) rather than clobbered (protects user-modified files
+ * on a re-install where the manifest was lost).
+ *
+ * @returns {{copied: string[], skipped: string[]}} relative paths (to dest root)
+ */
+function copyDirTracked(src, dest, force, rel = '', acc = { copied: [], skipped: [] }) {
+  const stat = fs.statSync(src);
+  if (stat.isFile()) {
+    if (fileExists(dest) && !force) {
+      acc.skipped.push(rel);
+    } else {
+      ensureDir(path.dirname(dest));
+      fs.copyFileSync(src, dest);
+      acc.copied.push(rel);
+    }
+    return acc;
+  }
+  if (stat.isDirectory()) {
+    ensureDir(dest);
+    for (const entry of fs.readdirSync(src)) {
+      copyDirTracked(path.join(src, entry), path.join(dest, entry), force,
+        rel ? path.join(rel, entry) : entry, acc);
+    }
+  }
+  return acc;
+}
+
 /**
  * Returns true if the path exists (file or directory).
  */
@@ -254,6 +287,7 @@ module.exports = {
 
   // File operations
   copyDirRecursive,
+  copyDirTracked,
   fileExists,
   readJSON,
   writeJSON,

package/templates/.claude/commands/bto-benchmark.md

@@ -1,302 +0,0 @@
-# /bto-benchmark — Deterministic Benchmarking of a Skill or Command
-
-## Usage
-```
-/bto-benchmark [path to skill directory or file]
-```
-
-## Parameters
-- $ARGUMENTS — Path to a skill directory (`.claude/skills/<name>/`), a command file (`.claude/commands/<name>.md`), a rule file (`.claude/rules/<name>.md`), or any structured artifact. Optionally include "verbose" to show expanded per-section diagnostics for all layers.
-
-## Protocol
-
-### Step 1: Load Skill and Module
-
-Read `.claude/skills/bto/SKILL.md`
-Read `.claude/skills/bto/modules/benchmark.md`
-Read `.claude/skills/bto/references/golden-samples.md`
-
-### Step 2: Validate Input
-
-If $ARGUMENTS is empty:
-- Ask: "Provide a path to the skill directory or artifact file you want to benchmark."
-- Stop and wait.
-
-Resolve the artifact path from $ARGUMENTS:
-- Strip any trailing slash
-- If the path points to a directory → look for `SKILL.md` inside it as the primary file, but include all files in the directory for context
-- If the path points to a file → use that file directly
-- If the path does not exist → report "Path not found: [path]" and stop
-
-### Step 3: Detect Artifact Type
-
-Auto-detect from path pattern:
-
-| Path Pattern | Detected Type |
-|-------------|--------------|
-| `.claude/skills/*/SKILL.md` or `.claude/skills/*/` | skill |
-| `.claude/commands/*.md` | command |
-| `.claude/rules/*.md` | rule |
-| `.claude/agents/*.md` | agent |
-| `researches/**/*.md` | research artifact |
-
-If type cannot be determined from path → infer from file content structure.
-
-### Step 4: Layer B0 — Golden Sample Comparison (Deterministic)
-
-**Purpose:** Compare artifact structure against the canonical golden sample for its type. Zero LLM cost.
-
-Load golden samples for the detected type from `references/golden-samples.md`.
-
-**Procedure:**
-
-1. Parse the artifact into a section tree (heading hierarchy, section lengths, ordering)
-2. Parse the matching golden sample into the same section tree format
-3. Compare across three structural axes:
-
-**Axis 1 — Section Coverage:**
-For each required section in the golden sample, check if the artifact contains a matching section (by heading text or semantic equivalent).
-- `section_coverage = matched_sections / total_golden_sections`
-
-**Axis 2 — Ordering Score:**
-Compare the ordering of matched sections against the golden sample ordering.
-- Use normalized Kendall tau distance: `ordering_score = 1 - (inversions / max_inversions)`
-- If fewer than 3 matched sections → ordering_score = 1.0 (too few to meaningfully compare)
-
-**Axis 3 — Proportion Score:**
-For each matched section, compute the ratio of artifact section length to golden sample section length.
-- `proportion_score = 1 - mean(|log(artifact_len / golden_len)|)` clamped to [0, 1]
-- Measures whether sections are proportionally sized (not too bloated, not too thin)
-
-**Display per-section MATCH/MISS table:**
-
-```
-Golden Section              Status    Artifact Section             Size Ratio
-─────────────────────────── ──────── ──────────────────────────── ──────────
-## Overview                 MATCH    ## Overview                  1.2x
-## Protocol                 MATCH    ## Protocol                  0.8x
-## Anti-Patterns            MATCH    ## Anti-Patterns             1.0x
-## Dependencies             MISS     —                            —
-## Quick Start              MATCH    ## Quick Start               1.5x
-```
-
-**Golden Similarity Score:**
-```
-B0 = section_coverage * 0.50 + ordering_score * 0.25 + proportion_score * 0.25
-```
-
-**Gate:** If B0 < 0.30 → BLOCK immediately. The artifact's structure is too far from the expected form to benchmark meaningfully.
-
-### Step 5: Layer B1 — Deterministic Test Suite
-
-**Purpose:** Run all applicable deterministic tests for the detected artifact type. Zero LLM cost.
-
-Execute all applicable checks from `benchmark.md` for the detected artifact type. These overlap with but extend the Layer 0 checks from `/bto-test`:
-
-**Universal Checks (U1-U12):**
-- U-01: File exists and is non-empty
-- U-02: UTF-8 encoding valid
-- U-03: Starts with level-1 heading
-- U-04: No placeholder text (`[TODO]`, `[TBD]`, `<INSERT>`, `[PLACEHOLDER]`)
-- U-05: No empty sections (heading with no content before next heading)
-- U-06: Consistent heading hierarchy (no h1→h3 jumps)
-- U-07: No broken internal cross-references
-- U-08: File size within bounds (200B – 100KB per file)
-- U-09: No trailing whitespace on lines
-- U-10: Standard Markdown only (no HTML unless in code blocks)
-- U-11: All code blocks properly closed
-- U-12: No duplicate top-level sections
-
-**Type-Specific Checks:**
-- Skill: SK-01 through SK-16 (SKILL.md exists, required sections, modules/, references/, examples/, etc.)
-- Command: CM-01 through CM-08 (Usage section, Parameters, Protocol steps, Checkpoint, Critical Rules, etc.)
-- Rule: RL-01 through RL-06 (Table format, detection signals, fix actions, no contradictions, etc.)
-- Agent: AG-01 through AG-04 (Model specified, isolation rules, naming convention, output format)
-
-**Display per-test PASS/FAIL table:**
-
-```
-ID      Check                              Result   Note
-─────── ──────────────────────────────────  ──────── ────────────────────────────
-U-01    File exists and is non-empty       PASS     8.4 KB
-U-02    UTF-8 encoding                     PASS
-...
-SK-01   SKILL.md exists at skill root      PASS
-SK-02   Has ## Overview section            PASS
-SK-03   Has ## Anti-Patterns section       FAIL     Section missing
-...
-```
-
-**Test Pass Rate:**
-```
-B1 = passed_tests / total_applicable_tests
-```
-
-**Gate:** If B1 < 0.60 → BLOCK. Too many structural failures to proceed to consistency probing.
-
-### Step 6: Layer B2 — Consistency Probe
-
-**Purpose:** Measure evaluation stability by running identical prompts across multiple agents. Detects artifacts that produce inconsistent interpretations.
-
-**Model:** haiku (cost-optimized)
-
-**Spawn 3 parallel haiku agents with the identical evaluation prompt:**
-
-Each agent receives the exact same prompt:
-```
-You are evaluating a Claude Code artifact for structural quality.
-Rate these 4 dimensions (0.0 to 1.0 each, two decimal places):
-1. STRUCTURE — Does the artifact follow a clear, logical organization?
-2. CLARITY — Are instructions unambiguous and actionable?
-3. COVERAGE — Does it address all aspects implied by its title/scope?
-4. CONSISTENCY — Is the internal terminology and style uniform?
-Output as JSON: {"structure": X.XX, "clarity": X.XX, "coverage": X.XX, "consistency": X.XX}
-```
-
-**Isolation:** Each agent evaluates independently. No cross-communication.
-
-**After all 3 return, compute structural agreement:**
-
-For each dimension:
-```
-agreement[dim] = 1 - (max(scores[dim]) - min(scores[dim]))
-```
-
-**Consistency Score:**
-```
-B2 = mean(agreement across all 4 dimensions)
-```
-
-**Interpretation:**
-- B2 > 0.85 → HIGH consistency — the artifact is unambiguously structured
-- B2 0.60-0.85 → MODERATE consistency — some sections are open to interpretation
-- B2 < 0.60 → LOW consistency — the artifact is structurally ambiguous
-
-**Display per-probe comparison:**
-
-```
-Dimension      Probe 1   Probe 2   Probe 3   Range    Agreement
-──────────── ────────── ────────── ────────── ──────── ──────────
-STRUCTURE      0.80       0.85       0.82      0.05     0.95
-CLARITY        0.70       0.75       0.65      0.10     0.90
-COVERAGE       0.60       0.70       0.55      0.15     0.85
-CONSISTENCY    0.75       0.78       0.73      0.05     0.95
-                                                Mean:    0.91
-```
-
-No gate on B2 — consistency is informational and feeds into the aggregate score.
-
-### Step 7: Layer B3 — Performance Metrics
-
-**Purpose:** Quantify token efficiency and information density. Zero LLM cost.
-
-**Metric 1 — Token Efficiency:**
-```
-token_efficiency = meaningful_content_tokens / total_tokens
-```
-Where `meaningful_content_tokens` excludes: blank lines, decorative separators, repeated boilerplate headers, and excessive whitespace. Target: > 0.70.
-
-**Metric 2 — Information Density:**
-```
-information_density = unique_concepts / total_sections
-```
-Where `unique_concepts` = count of distinct topics, terms, or instructions introduced. Measures whether each section contributes new information vs. repeating prior content. Target: > 2.0 concepts per section.
-
-**Metric 3 — Bloat Detection:**
-Identify sections where:
-- Section length > 3x the golden sample equivalent → BLOATED
-- Section length < 0.2x the golden sample equivalent → THIN
-- Section repeats > 30% of content from another section → REDUNDANT
-
-```
-bloat_score = 1 - (bloated_sections + thin_sections + redundant_sections) / total_sections
-```
-Clamped to [0, 1].
-
-**Performance Score:**
-```
-B3 = token_efficiency * 0.35 + normalize(information_density, 0, 4) * 0.35 + bloat_score * 0.30
-```
-Where `normalize(x, min, max)` clamps and scales x to [0, 1].
-
-**Display per-section metrics:**
-
-```
-Section                    Tokens   Concepts   Golden Ratio   Flag
-─────────────────────────  ──────── ────────── ──────────────  ──────────
-## Overview                 320      4          1.2x           OK
-## Protocol                 1840     12         0.8x           OK
-## Anti-Patterns            580      6          2.8x           BLOATED
-## Quick Start              95       2          0.3x           THIN
-## Dependencies             210      3          1.0x           OK
-```
-
-### Step 8: Aggregate & Gate
-
-**BENCHMARK_SCORE formula:**
-```
-BENCHMARK_SCORE = B0 * 0.30 + B1 * 0.35 + B2 * 0.15 + B3 * 0.20
-```
-
-**Weight rationale:**
-- B0 (Golden Comparison) at 0.30 — structural conformance is the primary benchmark signal
-- B1 (Test Suite) at 0.35 — deterministic correctness is the most reliable signal
-- B2 (Consistency) at 0.15 — stability matters but is a secondary signal
-- B3 (Performance) at 0.20 — efficiency matters for production artifacts
-
-**Gate:**
-- BENCHMARK_SCORE < 0.50 → **BLOCK** — artifact requires significant rework before evaluation
-- BENCHMARK_SCORE 0.50-0.70 → **WARN** — artifact has structural issues; proceed to TEST with caution
-- BENCHMARK_SCORE > 0.70 → **PASS** — artifact meets benchmark standards; ready for TEST
-
-Record `BENCHMARK_SCORE` for downstream consumption by `/bto-test` and `/bto`.
-
----
-
-## Checkpoint
-
-```
-═══════════════════════════════════════════════════════
-CHECKPOINT: BENCHMARK Complete
-<promise>BTO_BENCHMARKED</promise>
-Artifact: [path]
-Type: [detected type]
-
-Layer B0 (Golden):      X.XX — section coverage, ordering, proportions
-Layer B1 (Test Suite):  X.XX — Y/Z tests passed
-Layer B2 (Consistency): X.XX — agreement across 3 probes
-Layer B3 (Performance): X.XX — token efficiency, density, bloat
-
-BENCHMARK SCORE: X.XX [PASS / WARN / BLOCK]
-
-• "ок" — proceed to TEST
-• "покажи детали [B0/B1/B2/B3]" — expand layer details
-• "пропусти тест" — skip TEST (if PASS)
-═══════════════════════════════════════════════════════
-```
-
-Wait for user confirmation.
-
----
-
-## Modular Usage
-
-This command is also invoked internally by:
-- `/bto` — as a pre-flight step before TEST phase (if benchmark module is loaded)
-- `/bto-test` — optionally as a prerequisite gate (if user requests `benchmark` flag)
-
-The `BENCHMARK_SCORE` is available to downstream commands:
-- `/bto-test` may use it to calibrate Layer 1 expectations
-- `/bto-optimize` may use it to set a structural baseline floor
-
-## Critical Rules
-
-- Layer B0 and B1 are fully deterministic — no LLM calls, zero cost
-- Layer B2 uses haiku only — NEVER use sonnet or opus for consistency probes
-- Agent tool is REQUIRED for Layer B2 — do not run probes sequentially
-- Golden samples from `references/golden-samples.md` are the authoritative structural reference
-- If golden sample does not exist for the detected type → skip B0, set B0 = 0.50 (neutral), and log a warning
-- Report `BENCHMARK_SCORE` explicitly so downstream commands can consume it
-- BLOCK verdict at B0 or B1 halts the benchmark — do NOT proceed to subsequent layers
-- Layer B3 bloat detection uses golden sample proportions — without a golden sample, use absolute thresholds only
-- If "verbose" is in $ARGUMENTS, show expanded per-section diagnostics for all layers without prompting