@dzhechkov/keysarium-core 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# @dzhechkov/keysarium-core
+
+Core framework for building multi-agent pipelines with governance, memory, orchestration, verification, and trust tier systems.
+
+## What is keysarium-core?
+
+keysarium-core provides **domain-agnostic protocols** for any AI-powered multi-agent pipeline. It defines how agents coordinate, how decisions are verified, how the system learns from past executions, and how governance rules are enforced.
+
+Think of it as the "operating system" for multi-agent workflows. You bring the domain-specific skills and pipeline stages; keysarium-core provides the infrastructure.
+
+## Modules
+
+| Module | Purpose | Key Protocols |
+|--------|---------|---------------|
+| **governance/** | Structural rules and human checkpoints | Constitution, shard protocol, promise tags |
+| **memory/** | Persistent learning across executions | memory_query, memory_store, reward tracking, dream cycles |
+| **orchestration/** | Agent coordination and model routing | Queen protocol, 6 topologies, background workers, 3-tier routing |
+| **verification/** | Cryptographic integrity and isolation proofs | SHA-256 witness chain, judge attestation, audit trail |
+| **trust-tiers/** | Skill/artifact quality classification | 4-tier system (Advisory to Verified), promotion protocol |
+| **platform/** | Multi-platform config generation | Cursor, OpenCode, GitHub Copilot adapters |
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @dzhechkov/keysarium-core
+```
+
+### Using with an Existing Pipeline
+
+keysarium-core protocols are markdown-based. They define algorithms, schemas, and rules that AI agents read and follow. To integrate:
+
+1. **Governance:** Read `governance/constitution.md` at pipeline start to load invariants
+2. **Memory:** Call `memory_query()` before each stage, `memory_store()` after each checkpoint
+3. **Orchestration:** Select topology per stage from `orchestration/topology-selection.md`
+4. **Verification:** Create witness chain records at each stage completion
+5. **Trust Tiers:** Classify your skills using `trust-tiers/tier-system.md`
+
+### Using with Keysarium Research Pipeline
+
+```bash
+npm install @dzhechkov/keysarium @dzhechkov/keysarium-core
+```
+
+### Using with BTO Evaluation Pipeline
+
+```bash
+npm install @dzhechkov/skills-bto @dzhechkov/keysarium-core
+```
+
+## Architecture
+
+```
+@dzhechkov/keysarium-core          <-- You are here
+        ^                ^
+        |                |
+   peerDep          peerDep
+        |                |
+@dzhechkov/keysarium    @dzhechkov/skills-bto
+  (research)             (evaluation)
+```
+
+keysarium-core has **zero dependencies** on either consumer package. Both consumers declare keysarium-core as a peer dependency. Any team can use keysarium-core independently to build their own pipeline.
+
+## Module Reference
+
+### Governance
+
+- `constitution.md` — Universal invariants that must never be violated
+- `shard-protocol.md` — How to create per-stage governance rules that are reloaded at each stage to prevent context drift
+- `checkpoint-protocol.md` — Human synchronization points with promise tags for machine-readable completion signals
+
+### Memory
+
+- `memory-protocol.md` — Core `memory_query()` / `memory_store()` protocol for loading and persisting execution patterns with reward scores
+- `reward-tracker.md` — Analytics engine: per-stage averages, per-domain breakdowns, bottleneck detection, trend analysis
+- `dream-engine.md` — Background consolidation: builds concept graphs from accumulated data and generates cross-domain insights
+
+### Orchestration
+
+- `queen-protocol.md` — 10-step coordinator lifecycle: init, health, load, detect, shard, orchestrate, monitor, collect, store, report
+- `topology-selection.md` — 6 agent arrangement patterns: star, mesh, hierarchical, ring, hybrid, adaptive
+- `background-workers.md` — Non-blocking worker protocol: launch, status, stop, error handling, isolation rules
+- `model-routing.md` — 3-tier model assignment: haiku (fast/cheap), sonnet (balanced), opus (creative/complex)
+
+### Verification
+
+- `witness-chain.md` — SHA-256 hash-chain protocol for tamper-evident artifact integrity
+- `judge-attestation.md` — Cryptographic proof that evaluators operated independently
+- `audit-trail.md` — Complete evaluation history format with chain integrity verification
+
+### Trust Tiers
+
+- `tier-system.md` — 4-tier classification: Tier 0 (Advisory), Tier 1 (Structured), Tier 2 (Validated), Tier 3 (Verified)
+- `promotion-protocol.md` — How to promote skills between tiers based on evaluation evidence
+
+### Platform
+
+- `adapter-registry.md` — Central registry of supported AI coding platforms
+- `templates/cursor.md` — Cursor (.cursorrules) generation template
+- `templates/opencode.md` — OpenCode (.opencode/) generation template
+- `templates/copilot.md` — GitHub Copilot (.github/copilot-instructions.md) generation template
+
+## Building Your Own Pipeline
+
+To create a custom multi-agent pipeline using keysarium-core:
+
+1. Define your stages (equivalent to Keysarium's phases or BTO's layers)
+2. Create governance shards for each stage using `governance/shard-protocol.md`
+3. Choose topologies per stage using `orchestration/topology-selection.md`
+4. Configure model routing using `orchestration/model-routing.md`
+5. Implement witness chain at stage boundaries using `verification/witness-chain.md`
+6. Enable learning with `memory/memory-protocol.md`
+
+## Origins
+
+keysarium-core was extracted from the [Keysarium](https://github.com/dzhechko/product-keysarium-2026) project, which implements a 7-phase AI research pipeline. The protocols are inspired by:
+
+- **Ruflo** — 7-layer governance, 6 topologies, 3-tier model routing
+- **Agentic QE** — Trust tiers, reward-calibrated learning, dream cycles, PACT principles
+- **Quality Forge** — Portable brain containers, SHA-256 witness chains
+
+## License
+
+MIT

package/governance/checkpoint-protocol.md

@@ -0,0 +1,129 @@
+# Checkpoint Protocol — Human Synchronization Points
+
+> Universal protocol for checkpoints and semantic completion promises in multi-agent pipelines.
+
+## Overview
+
+A checkpoint is a mandatory pause point where the pipeline stops and waits for human confirmation before proceeding. Checkpoints serve three purposes:
+
+1. **Quality gate** — Human reviews the stage output before the next stage begins
+2. **Feedback loop** — Human provides corrections or approvals that calibrate the system
+3. **Completion signal** — A machine-readable promise tag records that the stage is done
+
+## Checkpoint Format
+
+```
+=====================================================
+CHECKPOINT {N}: {Stage Name} Complete
+<promise>{PROMISE_TAG}</promise>
+
+{2-3 line summary of what was accomplished}
+Artifacts created: {list of files}
+
+Options:
+- "ok" / "proceed" — advance to next stage
+- "deepen {section}" — elaborate on a specific section
+- "{specific feedback}" — adjust current stage output
+=====================================================
+```
+
+## Semantic Completion Promises
+
+### What is a Promise?
+
+A promise is a machine-readable tag embedded in the checkpoint output that signals the stage's completion status. It follows the format:
+
+```
+<promise>{TAG_NAME}</promise>
+```
+
+### Promise Rules
+
+1. A promise tag MUST only be emitted AFTER its conditions are verifiably met
+2. If conditions are NOT met, emit `<promise>{TAG_NAME}_INCOMPLETE</promise>` instead
+3. Downstream stages SHOULD check for upstream promises before starting
+4. Promise tags replace informal "stage done" signals with formal, parseable markers
+
+### Defining Promises for Your Pipeline
+
+Each stage in your pipeline should define:
+
+| Stage | Promise Tag | Conditions |
+|-------|-------------|------------|
+| Stage 0 | `{PIPELINE}_STAGE_0_COMPLETE` | All stage 0 artifacts created and validated |
+| Stage 1 | `{PIPELINE}_STAGE_1_COMPLETE` | All stage 1 artifacts created and validated |
+| ... | ... | ... |
+
+Replace `{PIPELINE}` with your pipeline's name (e.g., `RESEARCH`, `BTO`, `QE`).
+
+### Promise Validation
+
+At each stage start, the orchestrator should verify upstream promises:
+
+```
+1. Read the checkpoint history
+2. Check that all required upstream promises exist
+3. If any promise is missing or has _INCOMPLETE suffix:
+   a. Log: "Missing prerequisite: {TAG_NAME}"
+   b. Do NOT proceed — return to the incomplete stage
+```
+
+## Checkpoint Behavior
+
+### On "ok" Response
+
+1. Store the reward (1.0 — excellent) via memory_store
+2. Emit the stage's promise tag
+3. Advance to the next stage
+
+### On Feedback Response
+
+1. Parse feedback to determine scope
+2. If minor (one section): store reward 0.7, adjust, re-checkpoint
+3. If major (multiple sections): store reward 0.3, rework, re-checkpoint
+4. If restart requested: store reward 0.0, restart stage from scratch
+
+### On No Response
+
+If the session ends without a response at the checkpoint:
+- Do NOT store any reward (no record created)
+- Do NOT emit any promise tag
+- The stage remains in an indeterminate state
+
+## Checkpoint Timing
+
+Each checkpoint should display time spent vs. budget:
+
+```
+Time: {minutes_spent}m / {budget}m ({percentage}%)
+```
+
+If a stage exceeds its time budget, the checkpoint should include a warning:
+
+```
+Warning: Time budget exceeded ({percentage}% used). Consider wrapping up.
+```
+
+## Integration with Governance
+
+Checkpoints are the primary enforcement point for governance rules:
+
+1. Before displaying the checkpoint, run all constitution invariant checks
+2. Before displaying the checkpoint, validate all quality gates from the stage's shard
+3. If any gate fails, indicate it in the checkpoint and require the human to acknowledge
+
+## Integration with Memory
+
+After each checkpoint response:
+
+1. Determine the reward score based on the human's response type
+2. Call `memory_store()` with the stage context and reward
+3. This enables the system to learn which stages perform well and which need improvement
+
+## Integration with Witness Chain
+
+After each checkpoint with "ok" response:
+
+1. Compute the SHA-256 hash of the stage's primary artifact
+2. Append a record to the witness chain
+3. The promise tag is recorded in the chain record

package/governance/constitution.md

@@ -0,0 +1,144 @@
+# Constitution — Universal Invariants
+
+> Unbreakable rules for any multi-agent pipeline. These invariants are enforced at every stage gate and may never be violated.
+
+## Overview
+
+A Constitution defines the set of rules that are **always true** regardless of pipeline configuration, domain, or stage. They serve as hard enforcement gates — if an invariant is violated, the pipeline must halt.
+
+This is inspired by the 7-layer governance model (Ruflo) and the 7 constitutional invariants (Agentic QE).
+
+## Defining Invariants
+
+Each invariant follows this format:
+
+```markdown
+### INV-{NNN}: {Short Name}
+
+**Rule:** {One-sentence statement of what must always be true}
+
+**Enforcement:** {How to check — deterministic check, file existence, hash verification, etc.}
+
+**On violation:** {HALT | WARN | RETRY(N)}
+
+**Rationale:** {Why this invariant exists}
+```
+
+## Template Invariants
+
+The following invariants are recommended as a starting point for any multi-agent pipeline. Customize or extend based on your domain.
+
+### INV-001: Artifact Integrity
+
+**Rule:** Every artifact produced by a stage must be verifiable against its witness chain hash.
+
+**Enforcement:** After each stage completion, verify that the artifact file exists and its SHA-256 hash matches the chain record.
+
+**On violation:** HALT — artifact may have been tampered with.
+
+**Rationale:** Ensures no artifact is silently modified between stages.
+
+### INV-002: Stage Completion Signal
+
+**Rule:** A stage may not be marked complete without emitting a promise tag.
+
+**Enforcement:** Check that the stage's checkpoint includes a `<promise>` tag matching the expected value.
+
+**On violation:** HALT — downstream stages cannot trust upstream completion.
+
+**Rationale:** Promise tags are machine-readable signals that formalize stage gates.
+
+### INV-003: Human Checkpoint Required
+
+**Rule:** A stage may not auto-advance to the next stage without human confirmation at the checkpoint.
+
+**Enforcement:** The orchestrator must wait for explicit user input before proceeding.
+
+**On violation:** HALT — no auto-advancement permitted.
+
+**Rationale:** Human-in-the-loop prevents runaway automation and ensures quality.
+
+### INV-004: Evaluator Independence
+
+**Rule:** Evaluators (judges) in a multi-evaluator panel must operate in strict isolation. No evaluator may see another evaluator's score before submitting its own.
+
+**Enforcement:** Judge attestation protocol — each judge creates a hash of its evaluation before scores are shared.
+
+**On violation:** HALT — evaluation integrity compromised.
+
+**Rationale:** Independent evaluation prevents conformity collapse and produces more reliable quality signals.
+
+### INV-005: Loop Detection
+
+**Rule:** No agent may perform the same action more than 3 consecutive times without variation.
+
+**Enforcement:** Track the last 3 actions per agent. If identical, halt and escalate.
+
+**On violation:** WARN + escalate to coordinator.
+
+**Rationale:** Prevents infinite loops and wasted resources.
+
+### INV-006: Memory Consistency
+
+**Rule:** No contradictory patterns may coexist in the memory system.
+
+**Enforcement:** When storing a new pattern, check for existing patterns with the same pattern_id but conflicting content. If found, the newer pattern supersedes the older.
+
+**On violation:** WARN — resolve by keeping the most recent pattern.
+
+**Rationale:** Contradictory patterns degrade learning quality.
+
+### INV-007: No Unverified Claims
+
+**Rule:** Research outputs must not contain unverified factual claims presented as verified.
+
+**Enforcement:** Scan output artifacts for factual claims. Each must have a source citation or be marked as `[ANALYSIS]` or `[UNVERIFIED]`.
+
+**On violation:** HALT — return to research stage for verification.
+
+**Rationale:** Unverified claims undermine the credibility of the entire pipeline output.
+
+## Customization
+
+### Adding Domain-Specific Invariants
+
+To add invariants for your pipeline:
+
+1. Create a file `governance/constitution-{domain}.md` with additional invariants
+2. Number new invariants starting from INV-100 (to avoid conflicts with core)
+3. Follow the same format (Rule, Enforcement, On violation, Rationale)
+
+### Example: Banking Domain
+
+```markdown
+### INV-100: Data Perimeter
+
+**Rule:** No customer data may leave the security perimeter.
+
+**Enforcement:** All LLM calls must be to on-premise models (no external API calls).
+
+**On violation:** HALT — regulatory breach (FZ-152).
+```
+
+### Example: Evaluation Domain (BTO)
+
+```markdown
+### INV-100: Judge-Generator Separation
+
+**Rule:** The model used for generating an artifact must differ from the model used for evaluating it.
+
+**Enforcement:** Compare model IDs at evaluation start.
+
+**On violation:** HALT — self-evaluation bias.
+```
+
+## Enforcement Integration
+
+At each stage gate (checkpoint), the orchestrator should:
+
+1. Load the constitution (this file)
+2. Load any domain-specific constitution extensions
+3. Run each invariant's enforcement check
+4. If any check fails with HALT severity, stop the pipeline
+5. If any check fails with WARN severity, log and continue
+6. If any check fails with RETRY severity, retry up to N times before halting

package/governance/shard-protocol.md

@@ -0,0 +1,118 @@
+# Shard Protocol — Per-Stage Governance Rules
+
+> How to create and load governance shards that prevent context drift during long sessions.
+
+## Problem
+
+In long-running multi-agent sessions, rules loaded at the beginning drift out of the agent's active context after approximately 40 minutes. By the time later stages execute, the agent may have "forgotten" critical rules.
+
+## Solution
+
+Each pipeline stage gets its own **governance shard** — a focused set of rules that is re-read at the start of that stage. This ensures the agent always has the relevant rules in active context.
+
+## Shard Format
+
+Each shard is a markdown file with the following structure:
+
+```markdown
+# {Stage Name} Governance Shard
+
+## Time Budget
+- Allocated: {percentage}% of total pipeline time
+- Hard limit: {minutes} minutes
+
+## Prerequisites
+- Required upstream promises: [{PROMISE_TAG_1}, {PROMISE_TAG_2}]
+- Required input files: [{file_list}]
+
+## Skill to Load
+- Primary: {skill_name} (read SKILL.md at: {path})
+- Secondary: {skill_name} (optional)
+
+## Rules for This Stage
+1. {Rule 1 — specific to this stage}
+2. {Rule 2}
+3. ...
+
+## Quality Gates
+- [ ] {Gate 1 — what must be true for this stage to pass}
+- [ ] {Gate 2}
+- [ ] {Gate 3}
+
+## Promise Tag
+On successful completion, emit: `<promise>{PROMISE_TAG}</promise>`
+
+## Anti-Patterns for This Stage
+| Pattern | Fix |
+|---------|-----|
+| {Anti-pattern 1} | {Fix} |
+| {Anti-pattern 2} | {Fix} |
+```
+
+## Shard Naming Convention
+
+```
+{stage-id}.shard.md
+```
+
+Examples:
+- `stage-0-init.shard.md`
+- `stage-1-analysis.shard.md`
+- `stage-2-research.shard.md`
+- `bto-evaluation.shard.md`
+
+## Shard Loading Protocol
+
+At the start of each stage:
+
+1. **Determine shard path:** Construct the shard filename from the stage ID
+2. **Read shard:** Load the shard file content into the agent's context
+3. **Validate prerequisites:** Check that all required upstream promises have been emitted
+4. **Validate inputs:** Check that all required input files exist
+5. **Load skill:** If the shard specifies a skill, read its SKILL.md
+6. **Start timer:** Begin tracking time against the shard's budget
+7. **Execute stage:** Follow the shard's rules and quality gates
+
+## Shard Directory Location
+
+Shards should be stored in a dedicated directory within your pipeline configuration:
+
+```
+{pipeline-config}/shards/
+├── stage-0-init.shard.md
+├── stage-1-analysis.shard.md
+├── stage-2-research.shard.md
+├── stage-3-design.shard.md
+└── ...
+```
+
+## Creating a New Shard
+
+To create a shard for a new stage:
+
+1. Copy the template format above
+2. Fill in the stage-specific rules, quality gates, and anti-patterns
+3. Define the time budget (as a percentage of total pipeline time)
+4. List prerequisites (upstream promise tags)
+5. Specify the skill to load (if applicable)
+6. Define the promise tag this stage emits on completion
+7. Save to the shards directory with the naming convention
+
+## Shard Compilation
+
+For complex pipelines, the master configuration file (e.g., CLAUDE.md) can be "compiled" into per-stage shards at pipeline start:
+
+1. Read the master configuration
+2. Extract stage-relevant rules
+3. Generate shards with only the rules applicable to each stage
+4. Each agent receives a focused, lightweight governance document instead of the full configuration
+
+This reduces context load from hundreds of lines to 30-50 lines per stage.
+
+## Best Practices
+
+- Keep each shard under 100 lines for optimal context usage
+- Include only rules relevant to the current stage
+- Always include the promise tag for completion signaling
+- Always include time budget to prevent stages from running indefinitely
+- Review and update shards when pipeline rules change

package/index.md

@@ -0,0 +1,89 @@
+# keysarium-core Module Index
+
+> Manifest of all modules in @dzhechkov/keysarium-core v1.0.0
+
+## Module Registry
+
+| Module | Version | Files | Trust Tier | Description |
+|--------|---------|-------|------------|-------------|
+| governance | 1.0 | 3 | Tier 1 — Structured | Constitution, shards, checkpoints |
+| memory | 1.0 | 3 | Tier 1 — Structured | Reward-calibrated learning + dream cycles |
+| orchestration | 1.0 | 4 | Tier 1 — Structured | Coordinator protocol + topologies + workers |
+| verification | 1.0 | 3 | Tier 1 — Structured | Hash chains + judge attestation + audit trail |
+| trust-tiers | 1.0 | 2 | Tier 1 — Structured | 4-tier classification + promotion |
+| platform | 1.0 | 4 | Tier 0 — Advisory | Multi-platform adapter templates |
+
+## File Manifest
+
+```
+@dzhechkov/keysarium-core/
+├── package.json
+├── README.md
+├── index.md                           ← This file
+│
+├── governance/
+│   ├── constitution.md                ← v1.0 — Universal invariants
+│   ├── shard-protocol.md              ← v1.0 — Per-stage governance shards
+│   └── checkpoint-protocol.md         ← v1.0 — Checkpoints + promise tags
+│
+├── memory/
+│   ├── memory-protocol.md             ← v1.0 — memory_query + memory_store
+│   ├── reward-tracker.md              ← v1.0 — Analytics + pattern detection
+│   └── dream-engine.md                ← v1.0 — Background insight generation
+│
+├── orchestration/
+│   ├── queen-protocol.md              ← v1.0 — 10-step coordinator lifecycle
+│   ├── topology-selection.md          ← v1.0 — 6 topology types
+│   ├── background-workers.md          ← v1.0 — Non-blocking worker protocol
+│   └── model-routing.md               ← v1.0 — 3-tier model assignment
+│
+├── verification/
+│   ├── witness-chain.md               ← v1.0 — SHA-256 hash-chain
+│   ├── judge-attestation.md           ← v1.0 — Evaluator isolation proofs
+│   └── audit-trail.md                 ← v1.0 — Evaluation history format
+│
+├── trust-tiers/
+│   ├── tier-system.md                 ← v1.0 — 4-tier classification
+│   └── promotion-protocol.md          ← v1.0 — Tier advancement rules
+│
+└── platform/
+    ├── adapter-registry.md            ← v1.0 — Platform adapter definitions
+    └── templates/
+        ├── cursor.md                  ← v1.0 — Cursor generation template
+        ├── opencode.md                ← v1.0 — OpenCode generation template
+        └── copilot.md                 ← v1.0 — GitHub Copilot generation template
+```
+
+## Protocol Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2026-03-01 | Initial extraction from Keysarium v1.1.x and lib/ protocols |
+
+## Dependency Graph
+
+```
+governance ───> (standalone, no internal deps)
+memory ───> (standalone, no internal deps)
+orchestration ───> (standalone, no internal deps)
+verification ───> (standalone, no internal deps)
+trust-tiers ───> (standalone, no internal deps)
+platform ───> (standalone, no internal deps)
+```
+
+All modules are independent. A consumer may use any subset of modules without importing the others.
+
+## Schema Compatibility
+
+All JSON schemas defined in this package use `"version": "1.0"` as a schema version field. Consumers should check this field and warn if it does not match expected version.
+
+## Terminology Mapping
+
+When adapting core protocols for a specific domain:
+
+| Core Term | Replace With | Example |
+|-----------|-------------|---------|
+| stage | Your pipeline unit | "phase" (Keysarium), "layer" (BTO) |
+| project | Your work unit | "research" (Keysarium), "artifact" (BTO) |
+| domain | Your category system | "banking/retail" (Keysarium), "skill type" (BTO) |
+| skill | Your capability unit | "explore/research" (Keysarium), "build/test" (BTO) |