@dzhechkov/keysarium-core 1.0.0

package/platform/templates/cursor.md

@@ -0,0 +1,65 @@
+# Cursor Platform Template
+
+> Generates `.cursorrules` and optionally `.cursor/skills/` from pipeline source configuration.
+
+## Target Format
+
+Cursor uses a `.cursorrules` file in the project root. This is a plain-text/markdown file that Cursor's AI reads as project-level instructions. Optionally, `.cursor/skills/` can hold longer skill documents.
+
+## Generation Protocol
+
+### Step 1: Generate `.cursorrules`
+
+Create a `.cursorrules` file with the following structure:
+
+```
+# Project: {project name}
+
+## Project Overview
+{2-3 paragraphs describing the project purpose}
+
+## Rules
+{For each rule file, create a subsection with key bullet points.
+ Target: 3-8 bullet points per rule. Keep each to 1-2 lines.}
+
+## Skills
+{For each skill, extract:
+ - One-line description
+ - Core protocol steps (3-5 key steps)
+ - Key constraints (2-3 bullet points)
+ Keep each skill to 15-30 lines.}
+
+## Pipeline
+{Simplified pipeline overview: stage name | description | key output}
+
+## Anti-Patterns
+{Copy the anti-patterns table}
+```
+
+### Step 2: Generate `.cursor/skills/` (for large skills)
+
+If any skill exceeds 200 lines, create `.cursor/skills/{skill-name}.md` with the full content adapted for Cursor.
+
+### Step 3: Size Check
+
+Verify `.cursorrules` is under 10,000 tokens (~7,500 words). If over, further summarize skill sections.
+
+## Content Adaptation Rules
+
+| Source Element | Cursor Adaptation |
+|----------------|-------------------|
+| `Read: path/SKILL.md` | "Follow the {X} skill protocol" |
+| Agent tool references | "For parallel work, break into sub-tasks" |
+| Model routing | Omit (Cursor uses its own model) |
+| `$ARGUMENTS` | "User-provided input" |
+| Promise tags | Keep as documentation markers |
+| Checkpoint protocol | "Pause and confirm with user before proceeding" |
+
+## Example Output
+
+```
+.cursorrules                          (main instructions, <10K tokens)
+.cursor/
+└── skills/
+    └── {large-skill}.md              (full skill, if >200 lines)
+```

package/platform/templates/opencode.md

@@ -0,0 +1,69 @@
+# OpenCode Platform Template
+
+> Generates `.opencode/` directory structure from pipeline source configuration.
+
+## Target Format
+
+OpenCode uses a `.opencode/` directory with `config.yaml` and per-file skills and rules. This is the most structurally similar platform to Claude Code.
+
+## Generation Protocol
+
+### Step 1: Generate `.opencode/config.yaml`
+
+```yaml
+# OpenCode configuration for {project name}
+# Generated from source pipeline configuration
+
+project:
+  name: "{project name}"
+  description: "{project description}"
+
+instructions: |
+  {Critical rules: file conventions, quality requirements, checkpoints.
+   Keep to 30-50 lines.}
+
+skills_dir: ".opencode/skills"
+rules_dir: ".opencode/rules"
+```
+
+### Step 2: Generate `.opencode/skills/`
+
+For each skill, create `.opencode/skills/{skill-name}.md` with the full SKILL.md content adapted:
+- Replace source-specific paths with `.opencode/` paths
+- Replace Agent tool references with "Break into sub-tasks"
+- Omit model routing (platform-managed)
+
+### Step 3: Generate `.opencode/rules/`
+
+For each rule file, create `.opencode/rules/{rule-name}.md` with minimal adaptation:
+- Replace source paths
+- Keep tables and structured content intact
+- Remove platform-specific tool references
+
+### Step 4: Generate `.opencode/README.md`
+
+Brief README explaining the configuration structure and how to regenerate.
+
+## Content Adaptation Rules
+
+| Source Element | OpenCode Adaptation |
+|----------------|---------------------|
+| `source/skills/X/SKILL.md` | `.opencode/skills/X.md` |
+| `source/rules/X.md` | `.opencode/rules/X.md` |
+| `Read: path` | `See: adapted-path` |
+| Agent tool references | "Break into sub-tasks for parallel work" |
+| Model routing | Omit (platform-managed) |
+
+## Example Output
+
+```
+.opencode/
+├── config.yaml
+├── README.md
+├── skills/
+│   ├── skill-1.md
+│   └── skill-2.md
+└── rules/
+    ├── rule-1.md
+    └── rule-2.md
+```

package/trust-tiers/promotion-protocol.md

@@ -0,0 +1,144 @@
+# Promotion Protocol — Advancing Skills Between Tiers
+
+> How to promote a skill from one trust tier to the next.
+
+## Overview
+
+Skills start at the lowest tier that matches their current evidence level. They can be promoted to higher tiers by meeting the requirements defined in `tier-system.md`. This protocol defines the promotion process.
+
+## Promotion Paths
+
+```
+Tier 0 (Advisory)
+    ↓ Add references/ or modules/ + complete documentation
+Tier 1 (Structured)
+    ↓ Pass multi-evaluator panel with score >= 7.0
+Tier 2 (Validated)
+    ↓ Add deterministic eval tests + score >= 8.5
+Tier 3 (Verified)
+```
+
+## Promotion: Tier 0 to Tier 1
+
+### Requirements
+1. SKILL.md has complete protocol documentation (not just a stub)
+2. At least ONE of:
+   - `references/` directory with 2+ example files
+   - `modules/` directory with sub-components
+   - Structured output format documented (JSON schema or template)
+
+### Process
+1. Review SKILL.md for completeness
+2. Verify supporting materials exist
+3. Update skill metadata:
+   ```
+   trust_tier: 1
+   trust_tier_label: "Structured"
+   ```
+
+### No formal evaluation needed — this is a structural check.
+
+## Promotion: Tier 1 to Tier 2
+
+### Requirements
+1. All Tier 1 requirements met
+2. Pass a multi-evaluator panel evaluation
+3. Average score >= 7.0 out of 10.0
+4. No single judge score below 5.0
+
+### Process
+1. Submit the skill for multi-evaluator evaluation
+2. Panel of 3 judges independently evaluates the skill:
+   - **Domain Expert** (weight: 0.4) — evaluates domain accuracy and depth
+   - **Critic** (weight: 0.3) — looks for weaknesses and edge cases
+   - **Completeness Auditor** (weight: 0.3) — checks structural coverage
+3. Compute weighted average score
+4. If score >= 7.0:
+   - Update skill metadata:
+     ```
+     trust_tier: 2
+     trust_tier_label: "Validated"
+     bto_score: {score}
+     bto_date: "{YYYY-MM-DD}"
+     ```
+   - Record the full evaluation results
+5. If score < 7.0:
+   - Provide judge feedback for improvement
+   - Skill remains at Tier 1
+   - May re-evaluate after improvements
+
+### Judge Panel Rules
+- Judges operate in strict isolation (see judge-attestation.md)
+- Judges MUST be a different model tier than the skill's generation model
+- Judge scores are final unless disagreement > 3 points (escalate to meta-judge)
+
+## Promotion: Tier 2 to Tier 3
+
+### Requirements
+1. All Tier 2 requirements met
+2. Multi-evaluator panel score >= 8.5
+3. Deterministic eval test suite exists
+4. All eval tests pass consistently
+
+### Process
+1. Create eval test suite:
+   - Define test cases with known-good inputs and expected outputs
+   - Tests must be deterministic (same input always produces the same pass/fail)
+   - Minimum 5 test cases covering core functionality
+2. Run eval tests and verify all pass
+3. Re-evaluate with multi-evaluator panel (or use existing score if >= 8.5)
+4. If all conditions met:
+   - Update skill metadata:
+     ```
+     trust_tier: 3
+     trust_tier_label: "Verified"
+     bto_score: {score}
+     bto_date: "{YYYY-MM-DD}"
+     eval_tests: {count}
+     eval_tests_passing: {count}
+     ```
+
+## Demotion
+
+Skills can be demoted if:
+- Eval tests start failing (Tier 3 -> Tier 2)
+- Re-evaluation score drops below threshold (Tier 2 -> Tier 1)
+- Supporting materials are removed (Tier 1 -> Tier 0)
+
+Demotion is logged with reason and date.
+
+## Promotion History
+
+Each skill should maintain a promotion history:
+
+```json
+{
+  "skill_id": "{name}",
+  "current_tier": 2,
+  "history": [
+    {
+      "date": "2026-02-15",
+      "from_tier": 0,
+      "to_tier": 1,
+      "reason": "Added references/ directory with 3 examples"
+    },
+    {
+      "date": "2026-03-01",
+      "from_tier": 1,
+      "to_tier": 2,
+      "reason": "Passed BTO evaluation with score 7.8",
+      "score": 7.8,
+      "panel": ["domain-expert: 8.2", "critic: 7.5", "auditor: 8.0"]
+    }
+  ]
+}
+```
+
+## Cross-Project Tier Transfer
+
+When importing a skill from another project (via brain import):
+- The imported tier is treated as a **recommendation**, not a guarantee
+- The importing project may choose to:
+  1. Accept the tier as-is (trust the source)
+  2. Require re-evaluation at the current project (verify locally)
+  3. Demote by one tier (conservative approach)

package/trust-tiers/tier-system.md

@@ -0,0 +1,111 @@
+# Trust Tier System — 4-Tier Classification
+
+> Classify skills and artifacts by their validation evidence level.
+
+## Overview
+
+Not all skills and artifacts have the same level of validation. The Trust Tier system provides a 4-level classification that communicates how much confidence to place in a skill's output.
+
+## Tier Definitions
+
+| Tier | Label | Requirements | Confidence Level |
+|------|-------|-------------|-----------------|
+| **Tier 3** | Verified | Eval test suites with deterministic validation | Highest — production-ready |
+| **Tier 2** | Validated | Passed multi-evaluator panel with score >= 7.0 | High — tested and scored |
+| **Tier 1** | Structured | Documented protocol + references or modules | Medium — well-organized |
+| **Tier 0** | Advisory | Basic documentation only | Low — use with caution |
+
+## Tier Criteria (Detailed)
+
+### Tier 0 — Advisory
+
+**Minimum requirements:**
+- A SKILL.md (or equivalent) file exists
+- Basic instructions are documented
+
+**What it means:** The skill exists and has instructions, but has not been tested or validated. Output quality is unpredictable.
+
+**Flag in pipeline:** Display a warning when a Tier 0 skill is loaded:
+```
+WARNING: Skill '{name}' is Tier 0 (Advisory). Output may need extra review.
+```
+
+### Tier 1 — Structured
+
+**Minimum requirements:**
+- SKILL.md with complete protocol documentation
+- At least ONE of:
+  - `references/` directory with example inputs/outputs
+  - `modules/` directory with sub-components
+  - Structured output format (JSON schema, template)
+
+**What it means:** The skill is well-organized and has supporting materials, but has not been formally evaluated.
+
+### Tier 2 — Validated
+
+**Minimum requirements:**
+- All Tier 1 requirements
+- Passed a multi-evaluator panel (3+ judges) with average score >= 7.0 out of 10.0
+- Evaluation results recorded (date, scores, panel composition)
+
+**What it means:** The skill has been formally tested by multiple evaluators and scored above the quality threshold.
+
+**Recording:** Add to the skill's metadata:
+```
+trust_tier: 2
+trust_tier_label: "Validated"
+bto_score: 7.8
+bto_date: "2026-03-01"
+bto_panel: "domain-expert (8.2), critic (7.5), completeness-auditor (8.0)"
+```
+
+### Tier 3 — Verified
+
+**Minimum requirements:**
+- All Tier 2 requirements
+- Deterministic eval test suite exists
+- Tests pass consistently (reproducible results)
+- Score >= 8.5 on the multi-evaluator panel
+
+**What it means:** The skill has both human evaluation AND automated testing. This is the highest confidence level.
+
+## Classification Checklist
+
+Use this checklist to determine a skill's current tier:
+
+```
+[ ] SKILL.md exists                                          → Tier 0 minimum
+[ ] SKILL.md has complete protocol documentation             → Tier 0
+[ ] references/ OR modules/ OR structured output exists      → Tier 1
+[ ] Multi-evaluator panel score >= 7.0 recorded              → Tier 2
+[ ] Deterministic eval test suite exists and passes          → Tier 3
+[ ] Multi-evaluator panel score >= 8.5                       → Tier 3
+```
+
+## Tier Display Format
+
+When displaying skill tiers (e.g., in a health check):
+
+```
+Skills Health Check:
+  skill-name-1                  Tier 2 — Validated (score: 7.8)
+  skill-name-2                  Tier 1 — Structured
+  skill-name-3                  Tier 0 — Advisory (missing: references/)
+  skill-name-4                  Tier 3 — Verified (score: 8.9, tests: 12/12)
+```
+
+## Enforcement Rules
+
+| Context | Rule |
+|---------|------|
+| Production pipeline | Warn on Tier 0 skills, recommend alternatives |
+| Critical decisions | Require Tier 2+ skills for decision-making stages |
+| Evaluation panels | Judges should be Tier 1+ (Tier 0 judges produce unreliable scores) |
+| Knowledge export | Include tier metadata in brain export |
+
+## Integration
+
+The tier system integrates with:
+- **Memory Protocol:** Tier affects reward weight (higher tier = more trusted outcomes)
+- **Model Routing:** Tier can influence model selection (Tier 0 skills may need Tier 3 model to compensate)
+- **Brain Export:** Tier metadata is included in portable brain containers

package/verification/audit-trail.md

@@ -0,0 +1,154 @@
+# Audit Trail Protocol — Complete Evaluation History
+
+> Protocol for maintaining a complete, verifiable history of all evaluations and decisions in a pipeline.
+
+## Overview
+
+The Audit Trail combines the Witness Chain (artifact integrity) and Judge Attestation (evaluator isolation) into a unified evaluation history. It provides a single point of reference for auditing any decision made during pipeline execution.
+
+## Audit Trail Structure
+
+```
+{audit-root}/
+├── audit-log.json                     ← Master log of all events
+├── witness-chains/
+│   └── {project-slug}.json            ← Per-project witness chain
+├── attestations/
+│   └── {evaluation-id}.json           ← Per-evaluation attestation set
+└── decisions/
+    └── {decision-id}.json             ← Per-decision record
+```
+
+## Event Types
+
+| Event Type | Description | Source Protocol |
+|------------|-------------|----------------|
+| `artifact_created` | A stage artifact was produced | witness-chain.md |
+| `artifact_verified` | An artifact's hash was verified | witness-chain.md |
+| `artifact_modified` | An artifact was legitimately changed | witness-chain.md (repair) |
+| `evaluation_started` | A judge panel began evaluation | judge-attestation.md |
+| `evaluation_completed` | A judge panel finished scoring | judge-attestation.md |
+| `checkpoint_reached` | A human checkpoint was displayed | checkpoint-protocol.md |
+| `checkpoint_approved` | Human approved at checkpoint | checkpoint-protocol.md |
+| `checkpoint_revised` | Human requested changes at checkpoint | checkpoint-protocol.md |
+| `reward_stored` | A reward record was persisted | memory-protocol.md |
+| `decision_made` | A pipeline decision was recorded | (this protocol) |
+
+## Audit Log Schema
+
+```json
+{
+  "version": "1.0",
+  "pipeline_id": "string — unique pipeline execution ID",
+  "started_at": "ISO-8601",
+  "events": [
+    {
+      "event_id": "evt-{sequence:06d}",
+      "type": "string — event type from table above",
+      "timestamp": "ISO-8601",
+      "stage": "string — stage where event occurred",
+      "actor": "string — agent ID or 'human'",
+      "details": {
+        "description": "string — human-readable event description",
+        "artifact": "string — file path (if applicable)",
+        "hash": "sha256:... (if applicable)",
+        "score": 8.2,
+        "reward": 0.7
+      },
+      "references": {
+        "witness_chain_sequence": 3,
+        "attestation_id": "bto-eval-...",
+        "checkpoint_number": 2
+      }
+    }
+  ]
+}
+```
+
+## Decision Record Schema
+
+For significant decisions (e.g., which solution variant to choose, which candidate to promote):
+
+```json
+{
+  "decision_id": "dec-{YYYYMMDD}-{HHmmss}-{seq}",
+  "timestamp": "ISO-8601",
+  "stage": "string — stage where decision was made",
+  "decision_type": "variant_selection | tier_promotion | escalation | rollback",
+  "description": "string — what was decided",
+  "options_considered": [
+    {
+      "option_id": "A",
+      "description": "string",
+      "score": 8.2,
+      "selected": true
+    },
+    {
+      "option_id": "B",
+      "description": "string",
+      "score": 7.1,
+      "selected": false
+    }
+  ],
+  "rationale": "string — why this option was chosen",
+  "decided_by": "string — agent ID or 'human'",
+  "evidence": {
+    "attestation_id": "string (if decision was based on judge scores)",
+    "witness_chain_hash": "sha256:... (if decision was about an artifact)"
+  }
+}
+```
+
+## Audit Trail Operations
+
+### Initialize
+
+At pipeline start:
+1. Create `{audit-root}/` directory if it does not exist
+2. Create a new `audit-log.json` with the pipeline execution ID
+3. Log the `pipeline_started` event
+
+### Record Event
+
+At each significant point:
+1. Read the current audit-log.json
+2. Append the new event with an incremental event_id
+3. Write the updated audit-log.json
+
+### Query
+
+To find events related to a specific artifact or stage:
+1. Load audit-log.json
+2. Filter events by `stage`, `type`, or `details.artifact`
+3. Return matching events in chronological order
+
+### Verify Integrity
+
+To verify the audit trail has not been tampered with:
+1. For each `artifact_created` event, verify the hash in the witness chain
+2. For each `evaluation_completed` event, verify attestations
+3. Check that event timestamps are monotonically increasing
+4. Report any inconsistencies
+
+## Integration Points
+
+| Source | Audit Event | When |
+|--------|------------|------|
+| Witness Chain | `artifact_created` | After each stage artifact is hashed |
+| Judge Attestation | `evaluation_started`, `evaluation_completed` | At judge panel start/end |
+| Checkpoint Protocol | `checkpoint_reached`, `checkpoint_approved` | At each human checkpoint |
+| Memory Protocol | `reward_stored` | After each memory_store() call |
+
+## Retention Policy
+
+- Audit logs are retained for the lifetime of the project
+- They are NOT subject to the memory protocol's expiration rules
+- On brain export, the audit trail is included as metadata (event counts, not full events)
+
+## Regulatory Compliance Note
+
+For regulated domains (banking, healthcare), the audit trail provides:
+- Complete decision traceability
+- Proof of human oversight (checkpoint events)
+- Proof of evaluator independence (attestation events)
+- Artifact integrity verification (witness chain events)

package/verification/judge-attestation.md

@@ -0,0 +1,130 @@
+# Judge Attestation Protocol — Evaluator Isolation Proofs
+
+> Cryptographic proof that evaluators in a multi-evaluator panel operated independently.
+
+## Overview
+
+When multiple evaluators (judges) assess the same artifact, it is critical to prove they operated independently. This protocol defines how each judge creates a cryptographic attestation of its evaluation before seeing other judges' scores.
+
+## Constants
+
+```
+NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000"
+ATTESTATION_FILE = ".judge-attestations.json"
+HASH_PREFIX = "sha256:"
+STANDARD_PANEL_SIZE = 3
+HIGH_STAKES_PANEL_SIZE = 5
+```
+
+## Attestation Creation
+
+### Hash Input Construction
+
+Each judge's evaluation hash is computed from:
+
+```
+evaluation_hash = SHA-256(judge_id + "|" + artifact_hash + "|" + score + "|" + rationale_summary)
+```
+
+- `judge_id`: Unique identifier for the judge role
+- `artifact_hash`: SHA-256 hash of the artifact being evaluated
+- `score`: Numeric score as a string with one decimal place (e.g., "8.2")
+- `rationale_summary`: First 500 characters of the judge's rationale text
+
+### Computing the Artifact Hash
+
+Before any judge starts, compute the artifact hash:
+
+```bash
+ARTIFACT_HASH=$(${SHA_CMD} "path/to/artifact.md" | awk '{print $1}')
+```
+
+This proves all judges evaluated the same artifact.
+
+### Computing the Evaluation Hash
+
+After a judge completes its evaluation:
+
+```bash
+EVAL_HASH=$(printf '%s' "${JUDGE_ID}|${ARTIFACT_HASH}|${SCORE}|${RATIONALE_SUMMARY}" | ${SHA_CMD} | awk '{print $1}')
+```
+
+## Chain Linking
+
+Judges are recorded in a fixed order:
+
+1. First judge (previous = NULL_HASH)
+2. Second judge (previous = first judge's evaluation_hash)
+3. Third judge (previous = second judge's evaluation_hash)
+4. Additional judges continue the chain
+
+The chain records the ORDER of attestation finalization, proving each was recorded after the previous.
+
+## Isolation Proof Logic
+
+1. **Hash Independence:** Each evaluation_hash is computed from the judge's own data only
+2. **Chain Integrity:** The previous_attestation_hash links attestations in order but does NOT include other judges' scores
+3. **Timestamp Monotonicity:** Timestamps must be strictly increasing
+
+## Attestation File Schema
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "string — unique ID for this round",
+      "artifact_path": "string — path to evaluated artifact",
+      "artifact_hash": "sha256:<hex>",
+      "panel_size": 3,
+      "started_at": "ISO-8601",
+      "completed_at": "ISO-8601",
+      "attestations": [
+        {
+          "judge_id": "string — judge role identifier",
+          "score": 8.2,
+          "rationale_summary": "string — first 500 chars",
+          "evaluation_hash": "sha256:<hex>",
+          "timestamp": "ISO-8601",
+          "previous_attestation_hash": "sha256:<hex or null hash>"
+        }
+      ],
+      "final_score": 7.94,
+      "weights": {
+        "judge-1": 0.4,
+        "judge-2": 0.3,
+        "judge-3": 0.3
+      }
+    }
+  ]
+}
+```
+
+## Verification
+
+```
+1. Load attestation file
+2. For each evaluation round:
+   a. Verify artifact_hash matches across all attestations
+   b. For each attestation (index i):
+      i.   Reconstruct evaluation_hash from (judge_id, artifact_hash, score, rationale_summary)
+      ii.  Compare with stored evaluation_hash
+      iii. Verify chain link (previous_attestation_hash)
+      iv.  Verify timestamp monotonicity
+3. Produce verification report
+```
+
+## Meta-Judge Attestation
+
+When a meta-judge is invoked (e.g., disagreement exceeds threshold), it creates its own attestation appended to the chain. The meta-judge MAY reference other judges' scores (it is explicitly a synthesizer, not an independent evaluator).
+
+## Disagreement Detection Enhancement
+
+With attestations, disagreement detection gains cryptographic backing:
+
+```
+If max_score - min_score > threshold:
+  1. Verify all attestations are valid
+  2. Verify isolation (no influence detected)
+  3. If isolation verified: escalate to meta-judge (genuine disagreement)
+  4. If isolation violated: flag conformity collapse warning
+```