@dzhechkov/keysarium 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# @dzhechko/keysarium
+# @dzhechkov/keysarium
 
 **AI Case Research Toolkit for Claude Code**
 
-Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, agent templates, and hooks for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, shards, agent templates, and brain portability for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 ---
 
@@ -10,10 +10,10 @@ Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides s
 
 ```bash
 # One-command install via npx (no global install needed)
-npx @dzhechko/keysarium
+npx @dzhechkov/keysarium
 
 # Or install globally
-npm install -g @dzhechko/keysarium
+npm install -g @dzhechkov/keysarium
 keysarium init
 
 # Or without npm (standalone)
@@ -29,12 +29,12 @@ After installation, open Claude Code in your project directory and start using s
 | Component | Count | Description |
 |-----------|-------|-------------|
 | **Skills** | 6 | `explore`, `frontend-design`, `goap-research`, `presentation-storyteller`, `problem-solver`, `reverse-engineering` |
-| **Commands** | 11 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest` |
-| **Rules** | 7 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse` |
+| **Commands** | 13 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest`, `/brain-export`, `/brain-import` |
+| **Rules** | 10 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse`, `feedback-loops`, `model-routing`, `trust-tiers` |
+| **Shards** | 8 | Context shards for each phase: `phase-0-discovery`, `phase-1-explore`, `phase-2-research`, `phase-25-cjm`, `phase-3-solve`, `phase-4-architecture`, `phase-5-presentation`, `bto-evaluation` |
 | **Agent Templates** | 5 | `discovery-worker`, `research-worker`, `cjm-variant-worker`, `presentation-worker`, `parallel-research-orchestrator` |
-| **Hooks** | 3 | PreToolUse validation, PostToolUse notifications, audit logging |
 | **Library** | 4 | `phase-utils`, `agent-patterns`, `skill-loader`, `domain-templates` |
-| **Documentation** | 6 | Deployment, admin, user guide, infrastructure, architecture, flows |
+| **Documentation** | 12 | Deployment, admin, user guide, infrastructure, architecture, flows (for Keysarium and BTO) |
 
 Everything is installed into your project's `.claude/` directory and works natively with Claude Code.
 
@@ -65,22 +65,22 @@ Each phase produces concrete artifacts (Markdown documents, Mermaid diagrams, JS
 ## CLI Commands
 
 ```bash
-npx @dzhechko/keysarium                    # Full install (interactive, same as init)
-npx @dzhechko/keysarium init               # Install all components
-npx @dzhechko/keysarium init --minimal     # Only .claude/ (no docs, no lib)
-npx @dzhechko/keysarium init --with-docs   # Include documentation
-npx @dzhechko/keysarium init --force       # Overwrite existing files
-npx @dzhechko/keysarium init --dry-run     # Preview without making changes
-npx @dzhechko/keysarium update             # Update to latest version
-npx @dzhechko/keysarium remove             # Clean uninstall
-npx @dzhechko/keysarium list               # Show installed components
-npx @dzhechko/keysarium doctor             # Health check
+npx @dzhechkov/keysarium                    # Full install (interactive, same as init)
+npx @dzhechkov/keysarium init               # Install all components
+npx @dzhechkov/keysarium init --minimal     # Only .claude/ (no docs, no lib)
+npx @dzhechkov/keysarium init --with-docs   # Include documentation
+npx @dzhechkov/keysarium init --force       # Overwrite existing files
+npx @dzhechkov/keysarium init --dry-run     # Preview without making changes
+npx @dzhechkov/keysarium update             # Update to latest version
+npx @dzhechkov/keysarium remove             # Clean uninstall
+npx @dzhechkov/keysarium list               # Show installed components
+npx @dzhechkov/keysarium doctor             # Health check
 ```
 
 Flags can be combined:
 
 ```bash
-npx @dzhechko/keysarium init --minimal --force --dry-run
+npx @dzhechkov/keysarium init --minimal --force --dry-run
 ```
 
 ---
@@ -266,6 +266,22 @@ After completing research, extract reusable patterns:
 
 The harvester reviews completed projects, identifies universal patterns, decontextualizes them, and updates `TOOLKIT_HARVEST.md`.
 
+### Brain Portability
+
+Export and import accumulated knowledge between projects:
+
+```bash
+# Export knowledge as a portable JSON container
+/brain-export
+
+# Import a brain container into another project
+/brain-import path/to/brain.json
+```
+
+### Context Shards
+
+Shards (`.claude/shards/`) are lightweight context fragments that phases load on demand. They keep the main CLAUDE.md lean while providing phase-specific instructions, semantic completion promises, and quality checklists.
+
 ---
 
 ## Requirements
@@ -286,4 +302,4 @@ The harvester reviews completed projects, identifies universal patterns, deconte
 
 - **GitHub:** [https://github.com/dzhechko/product-keysarium-2026](https://github.com/dzhechko/product-keysarium-2026)
 - **Issues:** [https://github.com/dzhechko/product-keysarium-2026/issues](https://github.com/dzhechko/product-keysarium-2026/issues)
-- **npm:** [https://www.npmjs.com/package/@dzhechko/keysarium](https://www.npmjs.com/package/@dzhechko/keysarium)
+- **npm:** [https://www.npmjs.com/package/@dzhechkov/keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline for AI case studies, hackathons, and casariums",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -27,7 +27,7 @@ function getVersion() {
 // Help
 // ---------------------------------------------------------------------------
 function showHelp() {
-  console.log(bold('Usage:') + ' npx @dzhechko/keysarium ' + cyan('<command>') + dim(' [options]'));
+  console.log(bold('Usage:') + ' npx @dzhechkov/keysarium ' + cyan('<command>') + dim(' [options]'));
   console.log('');
   console.log(bold('Commands:'));
   console.log('  ' + green('init') + '      Install toolkit into current project ' + dim('(default)'));
@@ -45,10 +45,10 @@ function showHelp() {
   console.log('  ' + yellow('--version, -v') + ' Show version number');
   console.log('');
   console.log(bold('Examples:'));
-  console.log(dim('  $ ') + 'npx @dzhechko/keysarium init');
-  console.log(dim('  $ ') + 'npx @dzhechko/keysarium init --minimal --force');
-  console.log(dim('  $ ') + 'npx @dzhechko/keysarium update --dry-run');
-  console.log(dim('  $ ') + 'npx @dzhechko/keysarium doctor');
+  console.log(dim('  $ ') + 'npx @dzhechkov/keysarium init');
+  console.log(dim('  $ ') + 'npx @dzhechkov/keysarium init --minimal --force');
+  console.log(dim('  $ ') + 'npx @dzhechkov/keysarium update --dry-run');
+  console.log(dim('  $ ') + 'npx @dzhechkov/keysarium doctor');
   console.log('');
 }
 

package/src/commands/doctor.js

@@ -60,7 +60,7 @@ function checkFilesExist(manifest, targetDir) {
     return {
       passed: false,
       detail: `${missing.length} file(s) missing: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? '...' : ''}`,
-      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing files.`,
+      fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore missing files.`,
     };
   });
 }
@@ -76,7 +76,7 @@ function checkClaudeMd(targetDir) {
       return {
         passed: false,
         detail: 'CLAUDE.md not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} or ${cyan('@dzhechko/keysarium init --force')} to restore.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} or ${cyan('@dzhechkov/keysarium init --force')} to restore.`,
       };
     }
 
@@ -117,7 +117,7 @@ function checkSkillsComplete(targetDir) {
       return {
         passed: false,
         detail: '.claude/skills/ directory not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore skills.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore skills.`,
       };
     }
 
@@ -188,7 +188,7 @@ function checkCommandsPresent(targetDir) {
       return {
         passed: false,
         detail: '.claude/commands/ directory not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore commands.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore commands.`,
       };
     }
 
@@ -209,7 +209,7 @@ function checkCommandsPresent(targetDir) {
     return {
       passed: false,
       detail: `Missing ${missing.length} command(s): ${missing.join(', ')}`,
-      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing commands.`,
+      fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore missing commands.`,
     };
   });
 }
@@ -234,7 +234,7 @@ function checkRulesPresent(targetDir) {
       return {
         passed: false,
         detail: '.claude/rules/ directory not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore rules.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore rules.`,
       };
     }
 
@@ -255,7 +255,7 @@ function checkRulesPresent(targetDir) {
     return {
       passed: false,
       detail: `Missing ${missing.length} rule(s): ${missing.join(', ')}`,
-      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing rules.`,
+      fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore missing rules.`,
     };
   });
 }
@@ -271,7 +271,7 @@ function checkAgentsPresent(targetDir) {
       return {
         passed: false,
         detail: '.claude/agents/ directory not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore agents.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore agents.`,
       };
     }
 
@@ -298,7 +298,7 @@ function checkAgentsPresent(targetDir) {
     return {
       passed: false,
       detail: `Only ${mdFiles.length}/5 agent files found`,
-      fix: `Run ${cyan('@dzhechko/keysarium update')} to restore missing agent templates.`,
+      fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore missing agent templates.`,
     };
   });
 }
@@ -314,7 +314,7 @@ function checkSettingsValid(targetDir) {
       return {
         passed: false,
         detail: '.claude/settings.json not found',
-        fix: `Run ${cyan('@dzhechko/keysarium update')} to restore settings.`,
+        fix: `Run ${cyan('@dzhechkov/keysarium update')} to restore settings.`,
       };
     }
 
@@ -378,7 +378,7 @@ function checkResearchDir(targetDir) {
 // ---------------------------------------------------------------------------
 
 /**
- * `@dzhechko/keysarium doctor` — Health check for the toolkit installation.
+ * `@dzhechkov/keysarium doctor` — Health check for the toolkit installation.
  *
  * @param {object} options
  * @param {string}  options.targetDir — Project root directory
@@ -390,7 +390,7 @@ async function run(options) {
   // ── a) Check manifest exists ───────────────────────────────────────────
   if (!fileExists(manifestPath)) {
     logError('Keysarium is not installed in this directory.');
-    info(`Run ${cyan('@dzhechko/keysarium init')} to install.`);
+    info(`Run ${cyan('@dzhechkov/keysarium init')} to install.`);
     process.exit(1);
   }
 
@@ -401,7 +401,7 @@ async function run(options) {
   }
 
   console.log('');
-  info(bold(`Running health checks for @dzhechko/keysarium v${manifest.version}...`));
+  info(bold(`Running health checks for @dzhechkov/keysarium v${manifest.version}...`));
   console.log('');
 
   // ── b) Run all checks ─────────────────────────────────────────────────

package/src/commands/init.js

@@ -65,7 +65,7 @@ function installComponent(comp, templatesDir, targetDir) {
 // ---------------------------------------------------------------------------
 
 /**
- * `@dzhechko/keysarium init` — Install the toolkit into the target project.
+ * `@dzhechkov/keysarium init` — Install the toolkit into the target project.
  *
  * @param {object} options
  * @param {boolean} options.minimal   — Install only core (no lib)
@@ -82,7 +82,7 @@ async function run(options) {
   if (fileExists(manifestPath)) {
     if (!force) {
       warn('Keysarium is already installed in this directory.');
-      info(`Run ${cyan('@dzhechko/keysarium update')} to update, or use ${yellow('--force')} to overwrite.`);
+      info(`Run ${cyan('@dzhechkov/keysarium update')} to update, or use ${yellow('--force')} to overwrite.`);
       process.exit(1);
     }
     warn('Existing installation found — overwriting (--force).');

package/src/commands/list.js

@@ -53,7 +53,7 @@ function padRight(str, width) {
 // ---------------------------------------------------------------------------
 
 /**
- * `@dzhechko/keysarium list` — Show installed components and their status.
+ * `@dzhechkov/keysarium list` — Show installed components and their status.
  *
  * @param {object} options
  * @param {string}  options.targetDir — Project root directory
@@ -65,7 +65,7 @@ async function run(options) {
   // ── a) Read manifest ───────────────────────────────────────────────────
   if (!fileExists(manifestPath)) {
     warn('Keysarium is not installed in this directory.');
-    info(`Run ${cyan('@dzhechko/keysarium init')} to install.`);
+    info(`Run ${cyan('@dzhechkov/keysarium init')} to install.`);
     process.exit(1);
   }
 
@@ -79,7 +79,7 @@ async function run(options) {
 
   // ── Header ─────────────────────────────────────────────────────────────
   console.log('');
-  console.log(bold(`@dzhechko/keysarium v${manifest.version}`));
+  console.log(bold(`@dzhechkov/keysarium v${manifest.version}`));
   console.log(`Installed: ${manifest.installedAt ? manifest.installedAt.split('T')[0] : 'unknown'}`);
   if (manifest.updatedAt) {
     console.log(`Updated:   ${manifest.updatedAt.split('T')[0]}`);

package/src/commands/remove.js

@@ -82,7 +82,7 @@ function removeEmptyDirs(dirPath, stopDir) {
 // ---------------------------------------------------------------------------
 
 /**
- * `@dzhechko/keysarium remove` — Clean uninstall of the toolkit.
+ * `@dzhechkov/keysarium remove` — Clean uninstall of the toolkit.
  *
  * @param {object} options
  * @param {boolean} options.force     — Skip confirmation prompt
@@ -187,7 +187,7 @@ async function run(options) {
     console.log(`  ${dim('-')} ${skippedCount} file(s) already missing (skipped)`);
   }
   console.log('');
-  info(`To reinstall, run: ${cyan('@dzhechko/keysarium init')}`);
+  info(`To reinstall, run: ${cyan('@dzhechkov/keysarium init')}`);
   console.log('');
 
   process.exit(0);

package/src/commands/update.js

@@ -16,7 +16,7 @@ const {
 // ---------------------------------------------------------------------------
 
 /**
- * `@dzhechko/keysarium update` — Update an existing toolkit installation.
+ * `@dzhechkov/keysarium update` — Update an existing toolkit installation.
  *
  * @param {object} options
  * @param {boolean} options.dryRun    — Preview without writing anything
@@ -30,7 +30,7 @@ async function run(options) {
   // ── a) Read existing manifest ───────────────────────────────────────────
   if (!fileExists(manifestPath)) {
     logError('Keysarium is not installed in this directory.');
-    info(`Run ${cyan('@dzhechko/keysarium init')} to install.`);
+    info(`Run ${cyan('@dzhechkov/keysarium init')} to install.`);
     process.exit(1);
   }
 

package/templates/.claude/commands/brain-export.md

@@ -0,0 +1,121 @@
+---
+description: "Export accumulated knowledge as a portable brain container (JSON)"
+argument: "optional path to specific research directory, or 'all' for everything"
+---
+
+# Brain Export — Portable Knowledge Container
+
+Export accumulated knowledge, patterns, and evaluations into a portable JSON container
+that can be imported into other projects.
+
+## Protocol
+
+### Step 1: Scan Knowledge Sources
+
+Scan the following sources for exportable knowledge:
+1. `TOOLKIT_HARVEST.md` — harvested patterns and learnings
+2. `researches/*/` — all completed research directories
+3. `.claude/skills/*/SKILL.md` — skill metadata and trust tiers
+4. BTO evaluation reports (if any exist in researches)
+
+If `$ARGUMENTS` specifies a path, export only from that directory.
+If `$ARGUMENTS` is "all" or empty, export from all sources.
+
+### Step 2: Build Brain Container
+
+Construct a JSON structure:
+
+```json
+{
+  "version": "1.0",
+  "format": "keysarium-brain",
+  "exported_at": "[ISO 8601 timestamp]",
+  "source_project": "product-keysarium-2026",
+  "source_branch": "[current git branch]",
+
+  "skills": {
+    "[skill-name]": {
+      "trust_tier": 0-3,
+      "trust_tier_label": "Advisory|Structured|Validated|Verified",
+      "bto_score": null or float,
+      "last_evaluated": null or ISO date
+    }
+  },
+
+  "domain_patterns": {
+    "[domain]": {
+      "rules_applied": ["list of domain rules"],
+      "common_pitfalls": ["list"],
+      "successful_strategies": ["list"]
+    }
+  },
+
+  "research_summaries": [
+    {
+      "slug": "[case-slug]",
+      "domain": "[detected domain]",
+      "phases_completed": ["list of completed phases"],
+      "key_findings": ["top 3-5 findings"],
+      "chosen_cjm_variant": "A|B|C|D or null",
+      "presentation_score": null or float
+    }
+  ],
+
+  "harvest_patterns": [
+    {
+      "category": "skills|commands|rules|templates|patterns|snippets",
+      "name": "[pattern name]",
+      "description": "[what it does]",
+      "maturity": "beta|stable",
+      "used_in": ["project list"],
+      "content_hash": "[SHA-256 of content]"
+    }
+  ],
+
+  "pipeline_metrics": {
+    "total_cases_processed": 0,
+    "avg_phase_times": {},
+    "most_common_domain": null,
+    "bto_evaluations_run": 0
+  },
+
+  "metadata": {
+    "export_scope": "all|[specific path]",
+    "files_scanned": 0,
+    "patterns_extracted": 0
+  }
+}
+```
+
+### Step 3: Write Export File
+
+Write the JSON to: `keysarium-brain-[YYYY-MM-DD].json` in the project root.
+
+### Step 4: Generate Summary
+
+Display:
+```
+═══════════════════════════════════════════════════════
+Brain Export Complete
+
+File: keysarium-brain-[date].json
+Size: [file size]
+Skills exported: [N] (tiers: [breakdown])
+Research summaries: [N]
+Harvest patterns: [N]
+Domain patterns: [N domains]
+
+Import into another project:
+  /brain-import keysarium-brain-[date].json
+
+• "ок" — done
+• "покажи [section]" — preview section
+═══════════════════════════════════════════════════════
+```
+
+## Modular Reuse
+
+This export format is project-agnostic. Any multi-phase pipeline can:
+1. Define its own brain schema extending the base format
+2. Export domain-specific patterns
+3. Import patterns from other pipelines

package/templates/.claude/commands/brain-import.md

@@ -0,0 +1,115 @@
+---
+description: "Import a portable brain container into the current project"
+argument: "path to brain JSON file"
+---
+
+# Brain Import — Load External Knowledge
+
+Import a previously exported brain container to bootstrap knowledge in a new project.
+
+## Protocol
+
+### Step 1: Validate Brain File
+
+1. Read the JSON file from `$ARGUMENTS`
+2. Validate format:
+   - `version` field exists and is "1.0"
+   - `format` field is "keysarium-brain"
+   - Required sections present: `skills`, `harvest_patterns`, `metadata`
+3. If validation fails → show error and stop
+
+### Step 2: Selective Import
+
+Ask user what to import:
+
+```
+Brain file: [filename]
+Source project: [source_project]
+Exported: [exported_at]
+
+Available sections:
+  [1] Skills metadata ([N] skills) — trust tiers and BTO scores
+  [2] Domain patterns ([N] domains) — rules, pitfalls, strategies
+  [3] Research summaries ([N] cases) — findings and CJM choices
+  [4] Harvest patterns ([N] patterns) — reusable patterns and snippets
+  [5] Pipeline metrics — timing and performance data
+  [A] All sections
+
+Which sections to import? (comma-separated numbers or 'A' for all)
+```
+
+### Step 3: Merge Strategy
+
+For each imported section:
+
+**Skills metadata:**
+- Update trust_tier in SKILL.md files if imported tier is HIGHER than current
+- Never downgrade a tier
+- Log: "Skill [name]: tier [old] → [new] (from [source_project])"
+
+**Domain patterns:**
+- Append to existing domain knowledge (no overwrite)
+- Deduplicate by pattern name
+- Mark imported patterns with source: `[imported from: source_project, date]`
+
+**Research summaries:**
+- Store in `TOOLKIT_HARVEST.md` under "## Imported Research Summaries"
+- Read-only reference (don't create research directories)
+
+**Harvest patterns:**
+- Merge into `TOOLKIT_HARVEST.md`
+- Deduplicate by content_hash
+- Preserve maturity level from source
+
+**Pipeline metrics:**
+- Store as reference baseline
+- Don't overwrite current project metrics
+
+### Step 4: Write Import Log
+
+Create `brain-import-log-[YYYY-MM-DD].md` in project root:
+
+```markdown
+# Brain Import Log
+
+- Source: [filename]
+- Source project: [source_project]
+- Imported at: [timestamp]
+- Sections imported: [list]
+
+## Changes Made
+- [list of all changes with before/after]
+
+## Conflicts Resolved
+- [any deduplication or merge decisions]
+```
+
+### Step 5: Summary
+
+```
+═══════════════════════════════════════════════════════
+Brain Import Complete
+
+Source: [filename]
+Sections imported: [list]
+Skills updated: [N]
+Patterns merged: [N]
+Conflicts resolved: [N]
+
+Import log: brain-import-log-[date].md
+
+• "ок" — done
+• "покажи лог" — show full import log
+═══════════════════════════════════════════════════════
+```
+
+## Modular Reuse
+
+The import protocol handles:
+- Version compatibility checking
+- Selective import (user chooses sections)
+- Merge-not-overwrite strategy
+- Conflict resolution with logging
+- Audit trail via import log
+
+These patterns work for any knowledge transfer between projects.

package/templates/.claude/rules/checkpoint-protocol.md

@@ -7,14 +7,60 @@ Display a checkpoint banner and WAIT for user confirmation before proceeding.
 ```
 ═══════════════════════════════════════════════════════
 ⏸️ CHECKPOINT N: [Phase Name] Complete
+<promise>[PROMISE_TAG]</promise>
+
+[2-3 line summary of what was done]
+Files created: [list] ✅
+
+• "ок" — next phase
+• "углуби [section]" — elaborate
+• "[specific feedback]" — adjust
+═══════════════════════════════════════════════════════
+```
+
+## Semantic Completion Promises
+
+Each checkpoint MUST include the relevant promise tag to signal phase completion status.
+Promises are machine-readable markers that formalize phase gates.
+
+### Promise Tags by Phase
+
+| Phase | Promise Tag | Meaning |
+|-------|------------|---------|
+| Phase 0 | `<promise>DISCOVERY_COMPLETE</promise>` | JTBD + competitors + ROI analyzed |
+| Phase 1 | `<promise>CASE_EXPLORED</promise>` | Case fully understood, brief created |
+| Phase 2 | `<promise>RESEARCH_PARANOID_PASSED</promise>` | All claims verified, zero unverified |
+| Phase 2.5 | `<promise>CJM_VALIDATED</promise>` | CJM prototype created and variant chosen |
+| Phase 3 | `<promise>SOLUTION_DESIGNED</promise>` | Solution strategy formulated |
+| Phase 4 | `<promise>ARCHITECTURE_DEFINED</promise>` | C4 diagrams + sequence flows ready |
+| Phase 5 | `<promise>PRESENTATION_READY</promise>` | All 4 artifacts (05-08) created |
+| BTO L0 | `<promise>BTO_LAYER0_PASSED</promise>` | Deterministic checks passed |
+| BTO L2 | `<promise>BTO_LAYER2_SCORED</promise>` | Panel of 3 judges scored artifact |
+| BTO Opt | `<promise>BTO_OPTIMIZED</promise>` | Optimization converged |
+
+### Enhanced Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ CHECKPOINT N: [Phase Name] Complete
+<promise>[PROMISE_TAG]</promise>
+
 [2-3 line summary of what was done]
 Files created: [list] ✅
+
 • "ок" — next phase
 • "углуби [section]" — elaborate
 • "[specific feedback]" — adjust
 ═══════════════════════════════════════════════════════
 ```
 
+### Promise Validation Rules
+
+- A promise tag MUST only be emitted AFTER its conditions are verifiably met
+- If conditions are NOT met, emit `<promise>[TAG]_INCOMPLETE</promise>` instead
+- Downstream phases SHOULD check for upstream promises before starting
+- Promise tags serve as formal phase gates — they replace informal "phase done" signals
+
 ## Rules
 - NEVER skip checkpoints
 - NEVER auto-advance to the next phase without user confirmation