openhermes 1.2.2

package/harness/rules/skills-management.md

@@ -0,0 +1,165 @@
+# Skills Management — SKILL.md Format, Progressive Disclosure, Agent-Managed Lifecycle
+
+Sources: Hermes Agent SKILL.md frontmatter standard, progressive disclosure (L0/L1/L2), agent-managed skill lifecycle.
+
+## SKILL.md Frontmatter Format
+
+Every skill MUST have YAML frontmatter with these fields:
+
+```yaml
+---
+name: my-skill
+description: One-line description of what this skill does
+version: 1.0.0
+author: agent            # "agent" if auto-created, "user" if hand-authored
+tags: [testing, python]  # Search/discovery tags
+category: development    # Category grouping in skills directory
+trigger:                 # Keywords that trigger loading this skill
+  - test
+  - tdd
+  - coverage
+requires_tools:          # Toolsets this skill needs to function
+  - terminal
+config:                  # Optional config settings
+  - key: my.setting
+    description: What this controls
+    default: "value"
+---
+```
+
+### Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | yes | string | Unique skill name, used as directory name |
+| `description` | yes | string | One-line description shown in skill index |
+| `version` | no | string | Semver for curated skills |
+| `author` | no | string | "agent", "user", or origin identifier |
+| `tags` | no | string[] | Search/discovery tags |
+| `category` | no | string | Grouping category |
+| `trigger` | no | string[] | Keywords that trigger progressive load (Tier 0→Tier 1) |
+| `requires_tools` | no | string[] | Toolsets that must be present; skill is hidden when absent |
+| `fallback_for` | no | string[] | Show this skill ONLY when listed toolsets are unavailable |
+| `config` | no | object[] | Declared config settings injected on load |
+
+### Platform Restriction
+
+Skills can restrict themselves to specific OS platforms:
+
+```yaml
+platforms: [windows]        # Windows only
+platforms: [windows, linux] # Windows and Linux
+```
+
+When set, the skill is hidden on incompatible platforms. If omitted, loads on all platforms.
+
+### Conditional Activation (Fallback Skills)
+
+Skills can auto-show/hide based on available tools:
+
+```yaml
+fallback_for: [web]        # Show ONLY when web tools are unavailable
+requires_tools: [terminal] # Show ONLY when terminal tools are available
+```
+
+Example: A `web-search` skill with `fallback_for: [web]` stays hidden when web_search tool is available. When the tool is missing (no API key), the skill automatically appears as an alternative.
+
+## Progressive Disclosure Loading
+
+Skills use a token-efficient loading pattern inspired by Hermes:
+
+```
+Tier 0: Skill directory listing → names, descriptions, categories, tags (from frontmatter)
+         Do: read skills/<name>/SKILL.md frontmatter on demand
+         Cost: ~200 tokens for 11 skills
+
+Tier 1: Full SKILL.md content → load the markdown body when:
+         - User triggers a trigger keyword (matching `trigger` field)
+         - User explicitly names the skill or runs `/skill-name`
+         - A subtask or command references it
+         Cost: Varies by skill (1-5K tokens)
+
+Tier 2: Reference files → load scripts/, templates/, references/ only when:
+         - Executing the skill's procedure
+         - The skill instructs you to read a specific file
+         Cost: Varies
+```
+
+### Trigger-Table Lazy Loading
+
+Instead of preloading all skills at session start, use the trigger table:
+
+| Trigger keyword | Skill to load | Condition |
+|----------------|---------------|-----------|
+| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
+| "security", "auth", "xss" | security-review | Security-related work |
+| "verify", "build", "lint" | verification-loop | Build/before-PR context |
+
+### Duplicate Instruction Prevention
+
+Before loading a skill, check if its instructions are already covered by:
+- AGENTS.md rules already in context
+- Another skill already loaded this session
+
+If overlap is detected, skip loading to avoid context bloat.
+
+## Agent-Managed Skill Lifecycle
+
+The agent can create, update, and delete skills during sessions. This is the skill system's self-improvement loop.
+
+### When to Create a Skill
+
+- After completing a complex task (5+ tool calls) successfully
+- When you hit errors/dead ends and found the working path
+- When the user corrected your approach
+- When you discovered a non-trivial workflow
+
+### Skill Management Operations
+
+| Operation | Method | Use for |
+|-----------|--------|---------|
+| **Create** | Write `skills/<name>/SKILL.md` | New skill from scratch |
+| **Patch** | Edit specific text in `skills/<name>/SKILL.md` | Targeted fixes (preferred over full rewrite) |
+| **Edit** | Full rewrite of `skills/<name>/SKILL.md` | Major structural changes |
+| **Delete** | Remove `skills/<name>/` | Remove a skill (only if superseded; prefer archival) |
+| **Add reference** | Write `skills/<name>/references/<file>` | Supporting documentation |
+| **Add template** | Write `skills/<name>/templates/<file>` | Output format templates |
+| **Add script** | Write `skills/<name>/scripts/<file>` | Helper scripts |
+
+### Minimum Threshold for Creation
+
+- Never create a skill from a single data point.
+- Minimum: 3 verified successes or 3 same-type mistakes in 7 days.
+- Check existing skills via `hm_search` before creating to avoid duplicates.
+
+### Skill Quality Gates
+
+Every skill must have:
+1. Complete frontmatter with name, description, tags, trigger keywords
+2. A "When to Use" section with clear trigger conditions
+3. A "Procedure" section with step-by-step instructions
+4. A "Verification" section describing how to confirm it works
+5. A "Pitfalls" section noting known failure modes
+
+## Skill Directory Structure
+
+```
+skills/
+├── <name>/
+│   ├── SKILL.md               ← required
+│   ├── references/            ← additional docs
+│   ├── templates/             ← output formats
+│   └── scripts/               ← helper scripts
+```
+
+Skills live in three locations (discovered by OpenCode):
+- Project: `.opencode/skills/<name>/SKILL.md`
+- Global opencode: `~/.config/opencode/skills/<name>/SKILL.md`
+- Global agents: `~/.agents/skills/<name>/SKILL.md`
+
+## Verification
+
+After creating or updating a skill:
+1. Run the workflow defined in the SKILL.md.
+2. Verify it produces the expected outcome.
+3. Write a verification receipt via `hm_put` with class `verification_receipt`.

package/harness/rules/state-drift.md

@@ -0,0 +1,192 @@
+# State Drift Detection — Hash-Based Environment Fingerprinting
+
+## Problem Statement 
+Compression accumulates verification receipts across sessions. Without drift detection, the same receipt content gets compressed repeatedly even when:
+- Environment changed (node 18 → node 20, Python 3.9 → 3.11)  
+- File system state drifted (git commit hash changed)
+- Provider credentials rotated (API key in verification detail)
+
+This creates "phantom" compressed data that references stale environments.
+
+## Solution: Hash-Based Fingerprinting
+
+### Environment Fingerprint Schema
+```json
+{
+  "fingerprint": {
+    "cwd": "C:/path/to/project",
+    "harness_root": "C:/Users/nathan/.config/opencode/openhermes",
+    "project_root": "C:/path/to/project",
+    "project": "my-project",
+    "session_id": "session-123",
+    "os": "win32",
+    "release": "10.0.26100",
+    "arch": "x64",
+    "shell": "cmd.exe",
+    "provider": "lmstudio",
+    "model": "openhermes-1.x",
+    "sha256": "..."
+  }
+}
+```
+
+### Fingerprint Generation (Pre-Compression)
+```javascript
+function generateEnvironmentFingerprint() {
+  const cwd = process.cwd()
+  const provider = process.env.OPENCODE_PROVIDER || 'lmstudio'
+  const model = process.env.OPENCODE_MODEL || null
+
+  return hash(
+    `${cwd}${provider}${model || ''}`
+  )
+}
+```
+
+### Hash-Based Drift Detection (Post-Compression)
+```javascript
+function detectHashDrift(compressedSummary, lastFingerprint) {
+  const currentFingerprint = generateEnvironmentFingerprint()
+  
+  if (!lastFingerprint || currentFingerprint !== lastFingerprint) {
+    // Environment changed since last compression
+    return { drift: true, oldFp: lastFingerprint, newFp: currentFingerprint }
+  }
+  
+  return { drift: false }
+}
+```
+
+## Enforcement Points
+
+### Compress Event (Primary Guard)
+```javascript
+// In OpenHermes's built-in dynamic-context-pruning plugin
+function onCompress() {
+  // Generate fresh fingerprint before compressing
+  const currentFp = generateEnvironmentFingerprint()
+  
+  if (!lastFp || currentFp !== lastFp) {
+    // Drift detected → abort compression or truncate buffer
+    report.warn(`State drift: environment changed from ${lastFp} to ${currentFp}`)
+    return { truncated: true, reason: 'environment_drift' }
+  }
+  
+  lastFp = currentFp
+}
+```
+
+### Memory Write (Secondary Guard)  
+```javascript
+// In openhermes-memory MCP server  
+funtion putMemoryObject(obj) {
+  // Attach fingerprint to all new memory objects
+  obj.fingerprint = generateEnvironmentFingerprint()
+  
+  // Compare against last compressed buffer's fingerprint
+  if (!lastCompressedFp || obj.fingerprint !== lastCompressedFp) {
+    // New environment → flag for review or redact stale content
+    obj.stale_content_redacted = true
+  }
+}
+```
+
+### Session Resume (Recovery)
+```javascript
+// On session resume / checkpoint recovery 
+function recoverFromCheckpoint(checkpointData) {
+  const lastFp = checkpointData.lastCompressedFingerprint
+  const currentFp = generateEnvironmentFingerprint()
+  
+  if (!lastFp || currentFp !== lastFp) {
+    // Environment changed since checkpoint was created
+    report.warn(`Resume from checkpoint with environment drift: ${lastFp} → ${currentFp}`)
+    // Redact any compressed summaries that reference stale environments
+    redactStaleCompressedSummaries()
+  }
+}
+```
+
+## Hash Algorithm Selection
+
+### Recommended: SHA-256 (cryptographically strong, fast enough) ```javascript
+const fingerprint = sha256(
+  `${os.family}${os.version}${cwd}${gitState?.commit_hash}`
+).substring(0, 16) // Truncate to 16 hex chars for readability
+```
+
+### Alternatives (if performance needed)
+- **MD5**: Faster but weaker collision resistance. Use only if fingerprint is never displayed.
+- **CRC32**: Extremely fast, but collisions possible. Not recommended unless hash space is tiny.
+
+### Hash Space Considerations  
+- With SHA-256 truncated to 16 hex chars → 4^16 = ~4.3 billion unique fingerprints
+- Collision probability after N compressions ≈ N² / (8 × 2³¹) via birthday paradox
+- For typical sessions (<100,000 compresses), collision risk < 1e-5
+
+## Performance Characteristics
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| Generate fingerprint | ~5ms | Dominated by filesystem stat calls |
+| SHA-256 hash computation | ~0.5ms | Negligible compared to I/O |
+| Store in memory object | <1ms | Just a string assignment |
+
+## Fail-Safe Mechanisms
+
+### 1. Hash Collision (Extremely Rare)
+**What if two different environments produce same fingerprint?**
+- Use full SHA-256 for audit logging, truncated value for quick comparison
+- Log collision event with both hashes and manual review required
+- Store in `memory/audits/collision-events.json`
+
+### 2. Fingerprint Computation Failure  
+**What if filesystem stat fails (permission denied)?**
+- Fall back to previous valid fingerprint
+- Log error but continue operation
+- Schedule full drift check on next checkpoint
+
+### 3. Hash Algorithm Change
+**What if we upgrade from SHA-256 to SHA-3?**
+- Include hash algorithm identifier in fingerprint metadata
+- Parse both old and new format during resume
+- Migrate gracefully without data loss
+
+## Configuration & Overrides
+
+| Config | Default | Override |
+|--------|---------|----------|
+| `fingerprint_hash_algo` | "sha256" | "md5", "crc32" (performance mode only) |
+| `truncated_fingerprint_len` | 16 | 8, 4, 0 (full hash) |
+| `allow_drift_bypass` | false | Set to true for testing or known-good drift scenarios |
+
+## Compliance & Audit
+
+Every compressed summary must include:
+```json
+{
+  "fingerprint_at_compression": "fp_abc123def456",
+  "hash_algorithm": "sha256",
+  "truncated_length": 16,
+  "drift_detected": false,
+  "redaction_applied": false
+}
+```
+
+This allows:
+- Forensic reconstruction of environment at compression time
+- Verification that no phantom data exists in compressed buffer
+- Audit trail for compliance requirements (NIST, SOC2)
+
+## Integration with Other Rules
+
+- `rules/verification.md`: Fingerprint must be attached to all verification receipts  
+- `rules/runtime-guards.md`: Hash-based drift detection prevents credential exposure  
+- `commands/doctor.md`: Include fingerprint checks in the doctor workflow
+
+---
+
+**Status**: Active (enforcement: hard)  
+**Scope**: Global  
+**Created**: 2026-05-09T07:31:00Z  
+**Author**: agent (auto-generated via gap analysis)

package/harness/rules/verification.md

@@ -0,0 +1,88 @@
+# Verification — Skeptical Evidence Protocol
+
+Constitutional parent: principle 11 (`openhermes\constitution\soul.md`).
+Trust nothing without evidence. Every claim, instruction, document, and behavioral assertion must be confirmed by personal observation or a cached verification receipt before it may be treated as ground truth.
+
+Verification receipts prove that an artifact was observed in a particular state. They do not, by themselves, prove a live runtime claim unless the receipt captures a live-session artifact or log.
+
+## Core Stance
+
+- **User claims** — Input, not truth. Verify against evidence before acting.
+- **Document claims** — Documents rot. Cross-reference against current filesystem/code state.
+- **Code/script claims** — Past success does not guarantee present function. Run and check.
+- **Dependency claims** — Package manifests can be stale. Check the filesystem directly.
+
+## Verification Cache (Memory-Backed)
+
+Successful verifications are stored via `hm_put` so repeated checks of unchanged artifacts are skipped.
+
+### Cache Key
+
+Each verification receipt is keyed by:
+- **Artifact identity**: normalized file path, or logical identity (e.g., `state:dcp-installed`)
+- **Artifact fingerprint**: file `mtime` + `size` (files), or structured state hash (logical)
+
+### Cache Lifecycle
+
+1. **Before trusting a claim**: search memory (`hm_get` or `hm_list`) for matching receipt.
+2. **Receipt found + fingerprint matches**: artifact unchanged. Trust cached result. Skip re-verify.
+3. **Receipt found + fingerprint differs**: artifact changed. Re-verify. Stale receipt is invalid.
+4. **No receipt found**: verify fresh. Store receipt on success.
+
+### Receipt Storage
+
+Use `hm_put` with class `verification_receipt` — a dedicated memory class (schema: `schemas\verification_receipt.schema.json`). Receipts are stored as file-per-object in `memory\verification_receipts\<id>.json`.
+
+Required fields:
+- **artifact**: path or logical identity of the verified artifact
+- **fingerprint**: { path, mtime, size, sha256? } — determines cache validity
+- **environment**: { cwd, os, shell, provider, model } — reproducibility context
+- **method**: "command" | "read" | "test" | "schema-validate" | "manual-inspection" | "bash" | "grep"
+- **result**: "pass" | "fail" | "unknown"
+- **result_detail**: free-text description of what passed/failed, including output excerpts for command-based methods
+- **expires_at**: ISO-8601 — hard expiry regardless of fingerprint match (default: 30 days)
+- **supersedes / superseded_by**: receipt chains for audit trail
+
+Receipt quality gates:
+1. Every receipt must have: `artifact`, `method`, `result`, `result_detail`, `fingerprint`, `environment`, `provenance.session_id`, `created_at`.
+2. Command-based receipts (`method: command | bash | test`) must include output excerpt or exit code in `result_detail`.
+3. Config-based receipts (`method: manual-inspection | schema-validate | grep`) must reference the specific file paths inspected.
+4. No receipt may exceed 30 lines. If more detail is needed, link to a file.
+5. Receipts that supersede older ones must set `supersedes` to the prior receipt ID. The older receipt gets `superseded_by`.
+6. Receipts without `fingerprint` are non-cacheable — they must be re-verified every time.
+
+Receipts stored under `decision` with `v:` prefix are deprecated. Migrate to `verification_receipt` class on next touch.
+
+## Verification Methods by Artifact
+
+| Artifact | Method | Evidence |
+|---|---|---|
+| File content | `read` + grep for expected text | Exact match |
+| Code behavior | `bash` with test command | Exit 0 + expected output |
+| Directory structure | `read` (dir) or `glob` | Entry list matches |
+| Installation state | `bash (cmd --version)` | Non-error + expected version |
+| Document truth | Cross-ref code/filesystem | Primary source confirms doc |
+| User claim | Execute/read referenced thing | Primary evidence matches claim |
+
+## Contradiction Protocol
+
+When verification reveals evidence contradicts a document or user claim:
+
+1. **Pause** — do not proceed on either source.
+2. **Log** — `hm_put` as `constraint` or `backlog` with both claim and contradictory evidence.
+3. **Flag** — ask user about the discrepancy. Present both sides.
+4. **Resolve** — let user decide which source is authoritative. Update document if needed.
+
+## When to Skip Verification
+
+Allowed ONLY when:
+- Cached receipt with matching fingerprint exists in memory, AND
+- Artifact is confirmed unchanged (same mtime/hash)
+
+Never skip based on "should work" or "user says it works."
+
+## Integration
+
+- **Precedence** (`rules/precedence.md`): verified claim outranks unverified claim at same level. A verification receipt raises the effective priority of the claim it supports.
+- **Memory Retrieval** (`rules/retrieval.md`): verification receipts are queried before substantive work (Gate 2) and before task close (Gate 3).
+- **Self-Edit** (`AGENTS.md` Self-Edit Authority): adding verification receipts is unconditionally allowed.

package/harness/skills/.bundled_manifest

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "description": "Bundled skills shipped with openhermes. These are never subject to curator mutation, archive, or deletion.",
+  "skills": [
+    { "name": "api-design", "bundled": true, "created_by": "openhermes" },
+    { "name": "backend-patterns", "bundled": true, "created_by": "openhermes" },
+    { "name": "coding-standards", "bundled": true, "created_by": "openhermes" },
+    { "name": "e2e-testing", "bundled": true, "created_by": "openhermes" },
+    { "name": "frontend-patterns", "bundled": true, "created_by": "openhermes" },
+    { "name": "frontend-slides", "bundled": true, "created_by": "openhermes" },
+    { "name": "security-review", "bundled": true, "created_by": "openhermes" },
+    { "name": "strategic-compact", "bundled": true, "created_by": "openhermes" },
+    { "name": "tdd-workflow", "bundled": true, "created_by": "openhermes" },
+    { "name": "verification-loop", "bundled": true, "created_by": "openhermes" }
+  ],
+  "updated_at": "2026-05-08T00:00:00Z"
+}

package/harness/skills/.usage.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "description": "Skill usage telemetry. Bundled skills are excluded from curator mutation but tracked for load/use counts.",
+  "skills": {},
+  "updated_at": "2026-05-08T00:00:00Z"
+}