openhermes 2.6.1 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTEXT.md +18 -0
- package/ETHOS.md +15 -0
- package/README.md +135 -292
- package/bootstrap.mjs +174 -499
- package/harness/agents/openhermes.md +87 -0
- package/harness/codex/CONSTITUTION.md +70 -148
- package/harness/codex/ROUTING.md +126 -0
- package/harness/commands/oh-doctor.md +26 -0
- package/harness/instructions/CONVENTIONS.md +206 -206
- package/harness/instructions/RUNTIME.md +54 -31
- package/harness/skills/oh-builder/SKILL.md +98 -0
- package/harness/skills/oh-caveman/SKILL.md +33 -0
- package/harness/skills/oh-expert/SKILL.md +121 -0
- package/harness/skills/oh-freeze/SKILL.md +28 -0
- package/harness/skills/oh-gauntlet/SKILL.md +119 -0
- package/harness/skills/oh-grill/SKILL.md +77 -0
- package/harness/skills/oh-guard/SKILL.md +33 -0
- package/harness/skills/oh-handoff/SKILL.md +33 -0
- package/harness/skills/oh-health/SKILL.md +90 -0
- package/harness/skills/oh-init/SKILL.md +78 -0
- package/harness/skills/oh-investigate/SKILL.md +35 -0
- package/harness/skills/oh-issue/SKILL.md +36 -0
- package/harness/skills/oh-learn/SKILL.md +28 -0
- package/harness/skills/oh-manifest/SKILL.md +84 -0
- package/harness/skills/oh-plan-review/SKILL.md +128 -0
- package/harness/skills/oh-planner/SKILL.md +157 -0
- package/harness/skills/oh-prd/SKILL.md +35 -0
- package/harness/skills/oh-retro/SKILL.md +33 -0
- package/harness/skills/oh-review/SKILL.md +110 -0
- package/harness/skills/oh-security/SKILL.md +110 -0
- package/harness/skills/oh-ship/SKILL.md +39 -0
- package/harness/skills/oh-skill-craft/SKILL.md +107 -0
- package/harness/skills/oh-skills-link/SKILL.md +29 -0
- package/harness/skills/oh-skills-list/SKILL.md +31 -0
- package/harness/skills/oh-triage/SKILL.md +36 -0
- package/index.mjs +3 -58
- package/lib/harness-resolver.mjs +77 -0
- package/lib/logger.mjs +62 -0
- package/package.json +49 -53
- package/test/plugins-behavioral.test.mjs +64 -0
- package/test/plugins.test.mjs +62 -0
- package/autorecall.mjs +0 -237
- package/curator.mjs +0 -455
- package/harness/commands/build-fix.md +0 -60
- package/harness/commands/checkpoint.md +0 -68
- package/harness/commands/code-review.md +0 -71
- package/harness/commands/doctor.md +0 -42
- package/harness/commands/eval.md +0 -89
- package/harness/commands/go-build.md +0 -87
- package/harness/commands/go-review.md +0 -71
- package/harness/commands/harness-audit.md +0 -90
- package/harness/commands/learn.md +0 -37
- package/harness/commands/loop-start.md +0 -38
- package/harness/commands/loop-status.md +0 -30
- package/harness/commands/memory-search.md +0 -37
- package/harness/commands/model-route.md +0 -32
- package/harness/commands/ohc.md +0 -13
- package/harness/commands/orchestrate.md +0 -88
- package/harness/commands/plan.md +0 -53
- package/harness/commands/quality-gate.md +0 -35
- package/harness/commands/refactor-clean.md +0 -102
- package/harness/commands/rust-build.md +0 -78
- package/harness/commands/rust-review.md +0 -65
- package/harness/commands/security.md +0 -93
- package/harness/commands/setup-pm.md +0 -65
- package/harness/commands/skill-create.md +0 -99
- package/harness/commands/test-coverage.md +0 -80
- package/harness/commands/update-codemaps.md +0 -81
- package/harness/commands/update-docs.md +0 -67
- package/harness/commands/verify.md +0 -68
- package/harness/prompts/architect.txt +0 -189
- package/harness/prompts/build-cpp.md +0 -98
- package/harness/prompts/build-error-resolver.md +0 -44
- package/harness/prompts/build-go.md +0 -340
- package/harness/prompts/build-java.md +0 -140
- package/harness/prompts/build-kotlin.md +0 -137
- package/harness/prompts/build-rust.md +0 -108
- package/harness/prompts/code-reviewer.md +0 -40
- package/harness/prompts/doc-updater.md +0 -206
- package/harness/prompts/docs-lookup.md +0 -71
- package/harness/prompts/e2e-runner.txt +0 -317
- package/harness/prompts/explore.md +0 -42
- package/harness/prompts/harness-optimizer.md +0 -42
- package/harness/prompts/loop-operator.md +0 -53
- package/harness/prompts/planner.md +0 -37
- package/harness/prompts/refactor-cleaner.md +0 -256
- package/harness/prompts/review-cpp.md +0 -81
- package/harness/prompts/review-database.md +0 -261
- package/harness/prompts/review-go.md +0 -257
- package/harness/prompts/review-java.md +0 -113
- package/harness/prompts/review-kotlin.md +0 -143
- package/harness/prompts/review-python.md +0 -101
- package/harness/prompts/review-rust.md +0 -77
- package/harness/prompts/security-reviewer.md +0 -42
- package/harness/prompts/tdd-guide.md +0 -228
- package/harness/rules/audit.md +0 -84
- package/harness/rules/checkpointing.md +0 -75
- package/harness/rules/context-loading.md +0 -33
- package/harness/rules/credential-exposure.md +0 -0
- package/harness/rules/delegation.md +0 -80
- package/harness/rules/handoff.md +0 -267
- package/harness/rules/memory-management.md +0 -28
- package/harness/rules/precedence.md +0 -52
- package/harness/rules/promotion.md +0 -46
- package/harness/rules/ranking.md +0 -64
- package/harness/rules/retrieval.md +0 -94
- package/harness/rules/runtime-guards.md +0 -196
- package/harness/rules/self-heal.md +0 -79
- package/harness/rules/session-start.md +0 -34
- package/harness/rules/skills-management.md +0 -165
- package/harness/rules/state-drift.md +0 -192
- package/harness/rules/verification.md +0 -88
- package/harness/scripts/sync-commands.mjs +0 -259
- package/harness/skills/.bundled_manifest +0 -17
- package/harness/skills/.usage.json +0 -6
- package/harness/skills/api-design/SKILL.md +0 -523
- package/harness/skills/backend-patterns/SKILL.md +0 -598
- package/harness/skills/coding-standards/SKILL.md +0 -549
- package/harness/skills/e2e-testing/SKILL.md +0 -326
- package/harness/skills/frontend-patterns/SKILL.md +0 -642
- package/harness/skills/frontend-slides/SKILL.md +0 -184
- package/harness/skills/security-review/SKILL.md +0 -495
- package/harness/skills/strategic-compact/SKILL.md +0 -131
- package/harness/skills/tdd-workflow/SKILL.md +0 -463
- package/harness/skills/verification-loop/SKILL.md +0 -126
- package/lib/ambient-memory.mjs +0 -167
- package/lib/handoff.mjs +0 -176
- package/lib/hardening.mjs +0 -128
- package/lib/memory-tools-plugin.mjs +0 -365
- package/lib/ohc/block-sync.mjs +0 -69
- package/lib/ohc/compress/search.mjs +0 -152
- package/lib/ohc/compress/state.mjs +0 -76
- package/lib/ohc/config.mjs +0 -186
- package/lib/ohc/message-ids.mjs +0 -168
- package/lib/ohc/notify.mjs +0 -154
- package/lib/ohc/protected-patterns.mjs +0 -54
- package/lib/ohc/prune-apply.mjs +0 -134
- package/lib/ohc/pruner.mjs +0 -610
- package/lib/ohc/reaper.mjs +0 -70
- package/lib/ohc/state.mjs +0 -266
- package/lib/ohc/strategies/deduplication.mjs +0 -72
- package/lib/ohc/strategies/index.mjs +0 -2
- package/lib/ohc/strategies/purge-errors.mjs +0 -43
- package/lib/ohc/token-utils.mjs +0 -26
- package/lib/ohc/updater.mjs +0 -133
- package/lib/paths.mjs +0 -50
- package/lib/schema-validator.mjs +0 -77
- package/lib/search.mjs +0 -48
- package/schemas/audit.schema.json +0 -82
- package/schemas/backlog.schema.json +0 -63
- package/schemas/checkpoint.schema.json +0 -65
- package/schemas/constraint.schema.json +0 -62
- package/schemas/decision.schema.json +0 -63
- package/schemas/instinct.schema.json +0 -63
- package/schemas/loop-state.schema.json +0 -33
- package/schemas/mistake.schema.json +0 -64
- package/schemas/verification_receipt.schema.json +0 -88
- package/skill-builder.mjs +0 -88
|
@@ -1,196 +0,0 @@
|
|
|
1
|
-
# Runtime Guards — Prevent Stale Assumptions and Silent Failures
|
|
2
|
-
|
|
3
|
-
## Problem Statement
|
|
4
|
-
OpenHermes agents often operate on cached assumptions that become stale:
|
|
5
|
-
- "npm install is available" → but npm registry is down or rate-limited
|
|
6
|
-
- "git fetch works" → but remote repository was deleted or moved
|
|
7
|
-
- "Python 3.10 exists" → but path changed to Python 3.12
|
|
8
|
-
- "Provider endpoint reachable" → but load balancer rotated certificates
|
|
9
|
-
|
|
10
|
-
These stale assumptions cause:
|
|
11
|
-
- Silent failures (agent retries indefinitely)
|
|
12
|
-
- Wasted compute (re-running commands that will fail anyway)
|
|
13
|
-
- Incorrect behavior based on outdated information
|
|
14
|
-
|
|
15
|
-
## Guard Enforcement
|
|
16
|
-
|
|
17
|
-
### 1. Session Initialization Constraint
|
|
18
|
-
At session start, create active constraint with `enforcement: hard`:
|
|
19
|
-
```json
|
|
20
|
-
{
|
|
21
|
-
"id": "runtime-guards-session",
|
|
22
|
-
"class": "constraint",
|
|
23
|
-
"project": "current-project",
|
|
24
|
-
"summary": "Runtime guards for stale assumption prevention",
|
|
25
|
-
"constraints": [
|
|
26
|
-
{
|
|
27
|
-
"name": "never_cache_tool_state",
|
|
28
|
-
"description": "Every tool call → fresh verification, no cache lookup",
|
|
29
|
-
"enforcement": "hard"
|
|
30
|
-
},
|
|
31
|
-
{
|
|
32
|
-
"name": "environment_fingerprint_required",
|
|
33
|
-
"description": "Record OS, shell, cwd, provider, model at session start",
|
|
34
|
-
"enforcement": "hard"
|
|
35
|
-
}
|
|
36
|
-
]
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### 2. Pre-Tool-Call Check (Mandatory)
|
|
41
|
-
Before any tool invocation:
|
|
42
|
-
```javascript
|
|
43
|
-
// In agent execution loop
|
|
44
|
-
function beforeToolCall(toolName, args) {
|
|
45
|
-
// Verify environment matches session fingerprint
|
|
46
|
-
const envMatch = verifyEnvironmentFingerprint()
|
|
47
|
-
if (!envMatch) {
|
|
48
|
-
// Environment changed mid-session → hard fail or restart
|
|
49
|
-
throw new Error('Runtime guard: environment mismatch detected')
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
// Never trust cached tool results across sessions
|
|
53
|
-
return { allow: true, fingerprint: generateFingerprint() }
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
### 3. Compression Guard (Critical)
|
|
58
|
-
Before adding verification receipts to compress buffer:
|
|
59
|
-
```javascript
|
|
60
|
-
function filterReceiptForCompression(receipt) {
|
|
61
|
-
// Check if receipt contains stale environment markers
|
|
62
|
-
const hasStaleEnv = /\b(node_version|python_path|npm_registry)\b/.test(receipt.result_detail)
|
|
63
|
-
|
|
64
|
-
// Redact or remove stale artifacts before compression
|
|
65
|
-
if (hasStaleEnv) {
|
|
66
|
-
report.warn(`Excluding stale artifact from compress buffer: ${receipt.id}`)
|
|
67
|
-
return false
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
return true
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### 4. State Drift Detection (Post-Compression)
|
|
75
|
-
After each `compress` operation:
|
|
76
|
-
```javascript
|
|
77
|
-
function detectStateDrift(compressedBuffer) {
|
|
78
|
-
const fingerprints = computeFingerprints(compressedBuffer.receipts)
|
|
79
|
-
|
|
80
|
-
// Check for new environment markers that weren't in last fingerprint
|
|
81
|
-
const driftMarkers = [
|
|
82
|
-
/\b(node_version:.*?)(?!\b)/,
|
|
83
|
-
/\b(python_path:.*?)(?!\b)/,
|
|
84
|
-
/\b(npm_registry:.*?)(?!\b)/
|
|
85
|
-
]
|
|
86
|
-
|
|
87
|
-
for (const marker of driftMarkers) {
|
|
88
|
-
const matches = marker.exec(compressedBuffer.receipts)
|
|
89
|
-
if (matches && !lastFingerprint.includes(matches[0])) {
|
|
90
|
-
report.error(`State drift detected: ${matches[0]}`)
|
|
91
|
-
// Either revert compression or flag for manual review
|
|
92
|
-
return { drifted: true, marker: matches[0] }
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
lastFingerprint = fingerprints
|
|
97
|
-
return { drifted: false }
|
|
98
|
-
}
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## Enforcement Points
|
|
102
|
-
|
|
103
|
-
### Memory Write (ohc_save)
|
|
104
|
-
```javascript
|
|
105
|
-
// In openhermes-memory MCP server
|
|
106
|
-
function putMemoryObject(obj) {
|
|
107
|
-
// Check for stale environment markers before persisting
|
|
108
|
-
if (hasStaleEnvironmentMarker(obj.content)) {
|
|
109
|
-
obj.content = redactStaleMarkers(obj.content)
|
|
110
|
-
obj.stale = true
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
### Compress Event
|
|
116
|
-
```javascript
|
|
117
|
-
// In OpenHermes's built-in dynamic-context-pruning plugin
|
|
118
|
-
function onCompress() {
|
|
119
|
-
const compressBuffer = buildSummary()
|
|
120
|
-
// Filter out stale artifacts before adding to buffer
|
|
121
|
-
const filteredBuffer = compressBuffer.filter(receipt =>
|
|
122
|
-
!hasStaleEnvironmentMarker(receipt.result_detail)
|
|
123
|
-
)
|
|
124
|
-
return filteredBuffer
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### Session Resume (Recovery)
|
|
129
|
-
On session resume or checkpoint recovery:
|
|
130
|
-
```javascript
|
|
131
|
-
// Load all active memory objects
|
|
132
|
-
const loadedObjects = loadMemory()
|
|
133
|
-
// Immediately re-verify environment fingerprint for each receipt
|
|
134
|
-
const safeObjects = loadedObjects.map(obj => ({
|
|
135
|
-
...obj,
|
|
136
|
-
summary: redactStaleEnvironmentFromSummary(obj.summary)
|
|
137
|
-
}))
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
## Fail-Safe Mechanisms
|
|
141
|
-
|
|
142
|
-
### 1. Pattern Mismatch / False Negatives
|
|
143
|
-
**What if a new stale marker pattern emerges?**
|
|
144
|
-
- Add to `staleMarkers` array immediately (no deployment cycle needed)
|
|
145
|
-
- Run retrospective scan on last 30 days of memory objects
|
|
146
|
-
- Flag affected objects for manual review + redaction
|
|
147
|
-
|
|
148
|
-
### 2. Over-Redaction / False Positives
|
|
149
|
-
**What if legitimate data gets blocked?**
|
|
150
|
-
- Allow explicit bypass via constraint: `enforce_runtime_guards: false` (rare use case)
|
|
151
|
-
- Log all rejections to audit trail for review
|
|
152
|
-
- Provide CLI command: `/openhermes-audit` for staleness checks
|
|
153
|
-
|
|
154
|
-
### 3. Memory Corruption During Redaction
|
|
155
|
-
**What if redaction process itself fails?**
|
|
156
|
-
- Fall back to raw receipts (`opencode.db`) with full pattern matching
|
|
157
|
-
- Never silently skip redaction — always log and fail-closed
|
|
158
|
-
|
|
159
|
-
## Configuration & Overrides
|
|
160
|
-
|
|
161
|
-
| Config | Default | Override |
|
|
162
|
-
|--------|---------|----------|
|
|
163
|
-
| `enforce_runtime_guards` | true | Constraint or environment variable |
|
|
164
|
-
| `stale_marker_patterns_path` | rules/state-drift.md | Custom JSON/YAML file |
|
|
165
|
-
| `retrospective_scan_days` | 30 | 7-90 |
|
|
166
|
-
| `allow_bypass_paths` | [] (empty) | List of paths always excluded from filtering |
|
|
167
|
-
|
|
168
|
-
## Compliance & Audit
|
|
169
|
-
|
|
170
|
-
Every redacted memory object must include:
|
|
171
|
-
```json
|
|
172
|
-
{
|
|
173
|
-
"redacted_at": "2026-05-09T07:30:00Z",
|
|
174
|
-
"redaction_version": "1.0.0",
|
|
175
|
-
"patterns_applied": ["node_version", "python_path", ...],
|
|
176
|
-
"original_checksum": "sha256(original_content)"
|
|
177
|
-
}
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
This allows:
|
|
181
|
-
- Forensic reconstruction of what was redacted
|
|
182
|
-
- Verification that no legitimate data was accidentally blocked
|
|
183
|
-
- Audit trail for compliance requirements (SOC2, HIPAA, PCI)
|
|
184
|
-
|
|
185
|
-
## Integration with Other Rules
|
|
186
|
-
|
|
187
|
-
- `rules/verification.md`: Add "stale: true" to verification receipt schema
|
|
188
|
-
- `rules/state-drift.md`: Hash computation must exclude stale markers
|
|
189
|
-
- `commands/doctor.md`: Include fingerprint and staleness checks in the doctor workflow
|
|
190
|
-
|
|
191
|
-
---
|
|
192
|
-
|
|
193
|
-
**Status**: Active (enforcement: hard)
|
|
194
|
-
**Scope**: Global
|
|
195
|
-
**Created**: 2026-05-09T07:31:00Z
|
|
196
|
-
**Author**: agent (auto-generated via gap analysis)
|
|
@@ -1,79 +0,0 @@
|
|
|
1
|
-
# Self-Heal — Escalating Tier Model
|
|
2
|
-
|
|
3
|
-
Self-correction escalates through structured tiers. There is no self-termination. The system recovers by reducing risk, narrowing behavior, and preserving receipts.
|
|
4
|
-
|
|
5
|
-
## Tier 0 — Observe & Correct
|
|
6
|
-
|
|
7
|
-
**Trigger**: Any single mistake or unexpected outcome.
|
|
8
|
-
|
|
9
|
-
**Actions**:
|
|
10
|
-
1. Observe the issue — note what happened vs. what was expected.
|
|
11
|
-
2. Log a structured mistake record to `memory\mistakes\mistakes.jsonl` with root cause, fix, and prevention.
|
|
12
|
-
3. Attempt the smallest safe correction (one-line fix preferred, one-function max).
|
|
13
|
-
4. Verify the correction resolved the issue.
|
|
14
|
-
|
|
15
|
-
**Outcome**: Issue resolved. Mistake logged for future parity checks.
|
|
16
|
-
|
|
17
|
-
## Tier 1 — Add Prevention
|
|
18
|
-
|
|
19
|
-
**Trigger**: Same mistake type repeats within 7 days, or correction at T0 failed.
|
|
20
|
-
|
|
21
|
-
**Actions**:
|
|
22
|
-
1. Review the existing mistake record(s) for the type.
|
|
23
|
-
2. Add or refine a prevention rule — either a constraint record or a documented guard.
|
|
24
|
-
3. Run targeted verification against the original failure scenario.
|
|
25
|
-
4. If prevention rule already existed and failed → escalate to T2.
|
|
26
|
-
|
|
27
|
-
**Outcome**: Prevention rule active. Targeted verification passed.
|
|
28
|
-
|
|
29
|
-
## Tier 2 — Diagnosis & Review
|
|
30
|
-
|
|
31
|
-
**Trigger**: Prevention failed, systemic issue suspected, repeated uncertainty, or conflicting constraints.
|
|
32
|
-
|
|
33
|
-
**Actions**:
|
|
34
|
-
1. Delegate to specialist subagent for diagnosis:
|
|
35
|
-
- Build failure → `build-error-resolver`
|
|
36
|
-
- Logic/scope/other → `diagnose` skill + `code-reviewer`
|
|
37
|
-
- Security → `security-reviewer`
|
|
38
|
-
- Config/tool → `harness-optimizer` + openhermes audit
|
|
39
|
-
2. If structural (affects openhermes behavior across projects), generate a backlog item.
|
|
40
|
-
3. Run an openhermes audit to check for broken references, stale constraints, or provenance gaps.
|
|
41
|
-
4. Document findings and updated prevention rules.
|
|
42
|
-
|
|
43
|
-
**Outcome**: Root cause identified. Prevention rules hardened. Backlog item created if structural.
|
|
44
|
-
|
|
45
|
-
## Tier 3 — Constrained Safe Mode
|
|
46
|
-
|
|
47
|
-
**Trigger**: Repeated T2 escalation without resolution, or cascading failures across domains.
|
|
48
|
-
|
|
49
|
-
**Actions**:
|
|
50
|
-
1. Enter constrained safe mode:
|
|
51
|
-
- Narrow claims: only claim what is verified.
|
|
52
|
-
- Narrow actions: single-step operations only, no multi-file changes.
|
|
53
|
-
- Preserve receipts: log every action with provenance.
|
|
54
|
-
2. Produce a handoff-with-report:
|
|
55
|
-
- What happened (timeline of failures)
|
|
56
|
-
- What was attempted (T0, T1, T2 actions + results)
|
|
57
|
-
- Current state (what works, what doesn't)
|
|
58
|
-
- Recommended next action (human decision required)
|
|
59
|
-
- All mistake records and audit results attached
|
|
60
|
-
3. Do NOT continue autonomous work. Wait for human intervention or explicit override.
|
|
61
|
-
|
|
62
|
-
**Outcome**: Clean handoff state. System preserved. Human can resume without forensic reconstruction.
|
|
63
|
-
|
|
64
|
-
## Self-Heal Principles
|
|
65
|
-
|
|
66
|
-
- **Recover by reducing risk**: Narrow scope, add constraints, reduce ambition. Never widen scope to fix a problem.
|
|
67
|
-
- **No grandstanding**: Don't re-litigate decisions, don't blame tools, don't produce essay-length explanations. Terse, factual reports.
|
|
68
|
-
- **Preserve receipts**: Every tier escalation must be backed by logged evidence (mistake records, audit results, verification outputs).
|
|
69
|
-
- **No self-termination**: The session may be paused, constrained, or handed off, but never unilaterally terminated.
|
|
70
|
-
|
|
71
|
-
## Self-Edit Authority (Repeated for Reference)
|
|
72
|
-
|
|
73
|
-
| Tier | Allowed |
|
|
74
|
-
|------|---------|
|
|
75
|
-
| Unconditional | Append memory entries, mistake records, checkpoints, audit receipts |
|
|
76
|
-
| Conditional | Patch openhermes docs, schemas, templates, non-core rules; repair stale references in approved openhermes zones |
|
|
77
|
-
| Human approval required | Core AGENTS.md changes, model routing, permissions, major config, protected user-owned settings |
|
|
78
|
-
|
|
79
|
-
Full authority matrix is also in AGENTS.md.
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
# Session-Start Checklist
|
|
2
|
-
|
|
3
|
-
Run this at the start of every new session and every resume before substantive work.
|
|
4
|
-
|
|
5
|
-
## Checklist
|
|
6
|
-
|
|
7
|
-
1. Read `%USERPROFILE%\.config\opencode\AGENTS.md` and keep it active as the router.
|
|
8
|
-
2. Load openhermes status from `%USERPROFILE%\.config\opencode\ohc.json` if rule paths or memory locations are needed.
|
|
9
|
-
3. **Read autorecall cache**: If `openhermes\memory\recall\cache.json` exists, load it — it contains active checkpoint, constraints, decisions, and mistakes from the prior session. The autorecall plugin writes this at session start. Use this context before probing MCP tools.
|
|
10
|
-
4. Check only the smallest relevant curated memory slice in `openhermes\memory\`:
|
|
11
|
-
- latest checkpoint via `ohc_latest`
|
|
12
|
-
- active decisions via `ohc_latest` or a narrow `ohc_search`
|
|
13
|
-
- active constraints via `ohc_latest` or a narrow `ohc_search`
|
|
14
|
-
- recent same-type mistakes only if the task matches a known pattern
|
|
15
|
-
- do not read whole memory indexes unless the task is explicitly about index auditing or repair
|
|
16
|
-
5. If no relevant memory exists, proceed fresh without pretending there is prior state.
|
|
17
|
-
6. If last openhermes audit is missing or older than 7 days, flag `/harness-audit` as due.
|
|
18
|
-
7. Before substantial work, choose the smallest correct path:
|
|
19
|
-
- native read/grep/glob for search/gather
|
|
20
|
-
- `explore` subagent for multi-file analysis
|
|
21
|
-
- specialist subagent for substantive implementation, review, or diagnosis
|
|
22
|
-
|
|
23
|
-
## User Entry Points
|
|
24
|
-
|
|
25
|
-
- `/openhermes`: bootstrap openhermes state, summarize current readiness, and surface due actions.
|
|
26
|
-
- `/harness-audit`: run an openhermes audit workflow and return findings.
|
|
27
|
-
|
|
28
|
-
## Output Contract
|
|
29
|
-
|
|
30
|
-
Keep session-start output terse:
|
|
31
|
-
- current openhermes state
|
|
32
|
-
- memory found or not found
|
|
33
|
-
- audit freshness
|
|
34
|
-
- immediate next action
|
|
@@ -1,165 +0,0 @@
|
|
|
1
|
-
# Skills Management — SKILL.md Format, Progressive Disclosure, Agent-Managed Lifecycle
|
|
2
|
-
|
|
3
|
-
Sources: Hermes Agent SKILL.md frontmatter standard, progressive disclosure (L0/L1/L2), agent-managed skill lifecycle.
|
|
4
|
-
|
|
5
|
-
## SKILL.md Frontmatter Format
|
|
6
|
-
|
|
7
|
-
Every skill MUST have YAML frontmatter with these fields:
|
|
8
|
-
|
|
9
|
-
```yaml
|
|
10
|
-
---
|
|
11
|
-
name: my-skill
|
|
12
|
-
description: One-line description of what this skill does
|
|
13
|
-
version: 1.0.0
|
|
14
|
-
author: agent # "agent" if auto-created, "user" if hand-authored
|
|
15
|
-
tags: [testing, python] # Search/discovery tags
|
|
16
|
-
category: development # Category grouping in skills directory
|
|
17
|
-
trigger: # Keywords that trigger loading this skill
|
|
18
|
-
- test
|
|
19
|
-
- tdd
|
|
20
|
-
- coverage
|
|
21
|
-
requires_tools: # Toolsets this skill needs to function
|
|
22
|
-
- terminal
|
|
23
|
-
config: # Optional config settings
|
|
24
|
-
- key: my.setting
|
|
25
|
-
description: What this controls
|
|
26
|
-
default: "value"
|
|
27
|
-
---
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
### Field Reference
|
|
31
|
-
|
|
32
|
-
| Field | Required | Type | Description |
|
|
33
|
-
|-------|----------|------|-------------|
|
|
34
|
-
| `name` | yes | string | Unique skill name, used as directory name |
|
|
35
|
-
| `description` | yes | string | One-line description shown in skill index |
|
|
36
|
-
| `version` | no | string | Semver for curated skills |
|
|
37
|
-
| `author` | no | string | "agent", "user", or origin identifier |
|
|
38
|
-
| `tags` | no | string[] | Search/discovery tags |
|
|
39
|
-
| `category` | no | string | Grouping category |
|
|
40
|
-
| `trigger` | no | string[] | Keywords that trigger progressive load (Tier 0→Tier 1) |
|
|
41
|
-
| `requires_tools` | no | string[] | Toolsets that must be present; skill is hidden when absent |
|
|
42
|
-
| `fallback_for` | no | string[] | Show this skill ONLY when listed toolsets are unavailable |
|
|
43
|
-
| `config` | no | object[] | Declared config settings injected on load |
|
|
44
|
-
|
|
45
|
-
### Platform Restriction
|
|
46
|
-
|
|
47
|
-
Skills can restrict themselves to specific OS platforms:
|
|
48
|
-
|
|
49
|
-
```yaml
|
|
50
|
-
platforms: [windows] # Windows only
|
|
51
|
-
platforms: [windows, linux] # Windows and Linux
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
When set, the skill is hidden on incompatible platforms. If omitted, loads on all platforms.
|
|
55
|
-
|
|
56
|
-
### Conditional Activation (Fallback Skills)
|
|
57
|
-
|
|
58
|
-
Skills can auto-show/hide based on available tools:
|
|
59
|
-
|
|
60
|
-
```yaml
|
|
61
|
-
fallback_for: [web] # Show ONLY when web tools are unavailable
|
|
62
|
-
requires_tools: [terminal] # Show ONLY when terminal tools are available
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
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.
|
|
66
|
-
|
|
67
|
-
## Progressive Disclosure Loading
|
|
68
|
-
|
|
69
|
-
Skills use a token-efficient loading pattern inspired by Hermes:
|
|
70
|
-
|
|
71
|
-
```
|
|
72
|
-
Tier 0: Skill directory listing → names, descriptions, categories, tags (from frontmatter)
|
|
73
|
-
Do: read skills/<name>/SKILL.md frontmatter on demand
|
|
74
|
-
Cost: ~200 tokens for 11 skills
|
|
75
|
-
|
|
76
|
-
Tier 1: Full SKILL.md content → load the markdown body when:
|
|
77
|
-
- User triggers a trigger keyword (matching `trigger` field)
|
|
78
|
-
- User explicitly names the skill or runs `/skill-name`
|
|
79
|
-
- A subtask or command references it
|
|
80
|
-
Cost: Varies by skill (1-5K tokens)
|
|
81
|
-
|
|
82
|
-
Tier 2: Reference files → load scripts/, templates/, references/ only when:
|
|
83
|
-
- Executing the skill's procedure
|
|
84
|
-
- The skill instructs you to read a specific file
|
|
85
|
-
Cost: Varies
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
### Trigger-Table Lazy Loading
|
|
89
|
-
|
|
90
|
-
Instead of preloading all skills at session start, use the trigger table:
|
|
91
|
-
|
|
92
|
-
| Trigger keyword | Skill to load | Condition |
|
|
93
|
-
|----------------|---------------|-----------|
|
|
94
|
-
| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
|
|
95
|
-
| "security", "auth", "xss" | security-review | Security-related work |
|
|
96
|
-
| "verify", "build", "lint" | verification-loop | Build/before-PR context |
|
|
97
|
-
|
|
98
|
-
### Duplicate Instruction Prevention
|
|
99
|
-
|
|
100
|
-
Before loading a skill, check if its instructions are already covered by:
|
|
101
|
-
- AGENTS.md rules already in context
|
|
102
|
-
- Another skill already loaded this session
|
|
103
|
-
|
|
104
|
-
If overlap is detected, skip loading to avoid context bloat.
|
|
105
|
-
|
|
106
|
-
## Agent-Managed Skill Lifecycle
|
|
107
|
-
|
|
108
|
-
The agent can create, update, and delete skills during sessions. This is the skill system's self-improvement loop.
|
|
109
|
-
|
|
110
|
-
### When to Create a Skill
|
|
111
|
-
|
|
112
|
-
- After completing a complex task (5+ tool calls) successfully
|
|
113
|
-
- When you hit errors/dead ends and found the working path
|
|
114
|
-
- When the user corrected your approach
|
|
115
|
-
- When you discovered a non-trivial workflow
|
|
116
|
-
|
|
117
|
-
### Skill Management Operations
|
|
118
|
-
|
|
119
|
-
| Operation | Method | Use for |
|
|
120
|
-
|-----------|--------|---------|
|
|
121
|
-
| **Create** | Write `skills/<name>/SKILL.md` | New skill from scratch |
|
|
122
|
-
| **Patch** | Edit specific text in `skills/<name>/SKILL.md` | Targeted fixes (preferred over full rewrite) |
|
|
123
|
-
| **Edit** | Full rewrite of `skills/<name>/SKILL.md` | Major structural changes |
|
|
124
|
-
| **Delete** | Remove `skills/<name>/` | Remove a skill (only if superseded; prefer archival) |
|
|
125
|
-
| **Add reference** | Write `skills/<name>/references/<file>` | Supporting documentation |
|
|
126
|
-
| **Add template** | Write `skills/<name>/templates/<file>` | Output format templates |
|
|
127
|
-
| **Add script** | Write `skills/<name>/scripts/<file>` | Helper scripts |
|
|
128
|
-
|
|
129
|
-
### Minimum Threshold for Creation
|
|
130
|
-
|
|
131
|
-
- Never create a skill from a single data point.
|
|
132
|
-
- Minimum: 3 verified successes or 3 same-type mistakes in 7 days.
|
|
133
|
-
- Check existing skills via `ohc_search` before creating to avoid duplicates.
|
|
134
|
-
|
|
135
|
-
### Skill Quality Gates
|
|
136
|
-
|
|
137
|
-
Every skill must have:
|
|
138
|
-
1. Complete frontmatter with name, description, tags, trigger keywords
|
|
139
|
-
2. A "When to Use" section with clear trigger conditions
|
|
140
|
-
3. A "Procedure" section with step-by-step instructions
|
|
141
|
-
4. A "Verification" section describing how to confirm it works
|
|
142
|
-
5. A "Pitfalls" section noting known failure modes
|
|
143
|
-
|
|
144
|
-
## Skill Directory Structure
|
|
145
|
-
|
|
146
|
-
```
|
|
147
|
-
skills/
|
|
148
|
-
├── <name>/
|
|
149
|
-
│ ├── SKILL.md ← required
|
|
150
|
-
│ ├── references/ ← additional docs
|
|
151
|
-
│ ├── templates/ ← output formats
|
|
152
|
-
│ └── scripts/ ← helper scripts
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Skills live in three locations (discovered by OpenCode):
|
|
156
|
-
- Project: `.opencode/skills/<name>/SKILL.md`
|
|
157
|
-
- Global opencode: `~/.config/opencode/skills/<name>/SKILL.md`
|
|
158
|
-
- Global agents: `~/.agents/skills/<name>/SKILL.md`
|
|
159
|
-
|
|
160
|
-
## Verification
|
|
161
|
-
|
|
162
|
-
After creating or updating a skill:
|
|
163
|
-
1. Run the workflow defined in the SKILL.md.
|
|
164
|
-
2. Verify it produces the expected outcome.
|
|
165
|
-
3. Write a verification receipt via `ohc_save` with class `verification_receipt`.
|
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
# State Drift Detection — Hash-Based Environment Fingerprinting
|
|
2
|
-
|
|
3
|
-
## Problem Statement
|
|
4
|
-
Compression accumulates verification receipts across sessions. Without drift detection, the same receipt content gets compressed repeatedly even when:
|
|
5
|
-
- Environment changed (node 18 → node 20, Python 3.9 → 3.11)
|
|
6
|
-
- File system state drifted (git commit hash changed)
|
|
7
|
-
- Provider credentials rotated (API key in verification detail)
|
|
8
|
-
|
|
9
|
-
This creates "phantom" compressed data that references stale environments.
|
|
10
|
-
|
|
11
|
-
## Solution: Hash-Based Fingerprinting
|
|
12
|
-
|
|
13
|
-
### Environment Fingerprint Schema
|
|
14
|
-
```json
|
|
15
|
-
{
|
|
16
|
-
"fingerprint": {
|
|
17
|
-
"cwd": "C:/path/to/project",
|
|
18
|
-
"harness_root": "C:/Users/nathan/.config/opencode",
|
|
19
|
-
"project_root": "C:/path/to/project",
|
|
20
|
-
"project": "my-project",
|
|
21
|
-
"session_id": "session-123",
|
|
22
|
-
"os": "win32",
|
|
23
|
-
"release": "10.0.26100",
|
|
24
|
-
"arch": "x64",
|
|
25
|
-
"shell": "cmd.exe",
|
|
26
|
-
"provider": "lmstudio",
|
|
27
|
-
"model": "openhermes-1.x",
|
|
28
|
-
"sha256": "..."
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
### Fingerprint Generation (Pre-Compression)
|
|
34
|
-
```javascript
|
|
35
|
-
function generateEnvironmentFingerprint() {
|
|
36
|
-
const cwd = process.cwd()
|
|
37
|
-
const provider = process.env.OPENCODE_PROVIDER || 'lmstudio'
|
|
38
|
-
const model = process.env.OPENCODE_MODEL || null
|
|
39
|
-
|
|
40
|
-
return hash(
|
|
41
|
-
`${cwd}${provider}${model || ''}`
|
|
42
|
-
)
|
|
43
|
-
}
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
### Hash-Based Drift Detection (Post-Compression)
|
|
47
|
-
```javascript
|
|
48
|
-
function detectHashDrift(compressedSummary, lastFingerprint) {
|
|
49
|
-
const currentFingerprint = generateEnvironmentFingerprint()
|
|
50
|
-
|
|
51
|
-
if (!lastFingerprint || currentFingerprint !== lastFingerprint) {
|
|
52
|
-
// Environment changed since last compression
|
|
53
|
-
return { drift: true, oldFp: lastFingerprint, newFp: currentFingerprint }
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
return { drift: false }
|
|
57
|
-
}
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Enforcement Points
|
|
61
|
-
|
|
62
|
-
### Compress Event (Primary Guard)
|
|
63
|
-
```javascript
|
|
64
|
-
// In OpenHermes's built-in dynamic-context-pruning plugin
|
|
65
|
-
function onCompress() {
|
|
66
|
-
// Generate fresh fingerprint before compressing
|
|
67
|
-
const currentFp = generateEnvironmentFingerprint()
|
|
68
|
-
|
|
69
|
-
if (!lastFp || currentFp !== lastFp) {
|
|
70
|
-
// Drift detected → abort compression or truncate buffer
|
|
71
|
-
report.warn(`State drift: environment changed from ${lastFp} to ${currentFp}`)
|
|
72
|
-
return { truncated: true, reason: 'environment_drift' }
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
lastFp = currentFp
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
### Memory Write (Secondary Guard)
|
|
80
|
-
```javascript
|
|
81
|
-
// In openhermes-memory MCP server
|
|
82
|
-
funtion putMemoryObject(obj) {
|
|
83
|
-
// Attach fingerprint to all new memory objects
|
|
84
|
-
obj.fingerprint = generateEnvironmentFingerprint()
|
|
85
|
-
|
|
86
|
-
// Compare against last compressed buffer's fingerprint
|
|
87
|
-
if (!lastCompressedFp || obj.fingerprint !== lastCompressedFp) {
|
|
88
|
-
// New environment → flag for review or redact stale content
|
|
89
|
-
obj.stale_content_redacted = true
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
### Session Resume (Recovery)
|
|
95
|
-
```javascript
|
|
96
|
-
// On session resume / checkpoint recovery
|
|
97
|
-
function recoverFromCheckpoint(checkpointData) {
|
|
98
|
-
const lastFp = checkpointData.lastCompressedFingerprint
|
|
99
|
-
const currentFp = generateEnvironmentFingerprint()
|
|
100
|
-
|
|
101
|
-
if (!lastFp || currentFp !== lastFp) {
|
|
102
|
-
// Environment changed since checkpoint was created
|
|
103
|
-
report.warn(`Resume from checkpoint with environment drift: ${lastFp} → ${currentFp}`)
|
|
104
|
-
// Redact any compressed summaries that reference stale environments
|
|
105
|
-
redactStaleCompressedSummaries()
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
## Hash Algorithm Selection
|
|
111
|
-
|
|
112
|
-
### Recommended: SHA-256 (cryptographically strong, fast enough) ```javascript
|
|
113
|
-
const fingerprint = sha256(
|
|
114
|
-
`${os.family}${os.version}${cwd}${gitState?.commit_hash}`
|
|
115
|
-
).substring(0, 16) // Truncate to 16 hex chars for readability
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
### Alternatives (if performance needed)
|
|
119
|
-
- **MD5**: Faster but weaker collision resistance. Use only if fingerprint is never displayed.
|
|
120
|
-
- **CRC32**: Extremely fast, but collisions possible. Not recommended unless hash space is tiny.
|
|
121
|
-
|
|
122
|
-
### Hash Space Considerations
|
|
123
|
-
- With SHA-256 truncated to 16 hex chars → 4^16 = ~4.3 billion unique fingerprints
|
|
124
|
-
- Collision probability after N compressions ≈ N² / (8 × 2³¹) via birthday paradox
|
|
125
|
-
- For typical sessions (<100,000 compresses), collision risk < 1e-5
|
|
126
|
-
|
|
127
|
-
## Performance Characteristics
|
|
128
|
-
|
|
129
|
-
| Operation | Time | Notes |
|
|
130
|
-
|-----------|------|-------|
|
|
131
|
-
| Generate fingerprint | ~5ms | Dominated by filesystem stat calls |
|
|
132
|
-
| SHA-256 hash computation | ~0.5ms | Negligible compared to I/O |
|
|
133
|
-
| Store in memory object | <1ms | Just a string assignment |
|
|
134
|
-
|
|
135
|
-
## Fail-Safe Mechanisms
|
|
136
|
-
|
|
137
|
-
### 1. Hash Collision (Extremely Rare)
|
|
138
|
-
**What if two different environments produce same fingerprint?**
|
|
139
|
-
- Use full SHA-256 for audit logging, truncated value for quick comparison
|
|
140
|
-
- Log collision event with both hashes and manual review required
|
|
141
|
-
- Store in `memory/audits/collision-events.json`
|
|
142
|
-
|
|
143
|
-
### 2. Fingerprint Computation Failure
|
|
144
|
-
**What if filesystem stat fails (permission denied)?**
|
|
145
|
-
- Fall back to previous valid fingerprint
|
|
146
|
-
- Log error but continue operation
|
|
147
|
-
- Schedule full drift check on next checkpoint
|
|
148
|
-
|
|
149
|
-
### 3. Hash Algorithm Change
|
|
150
|
-
**What if we upgrade from SHA-256 to SHA-3?**
|
|
151
|
-
- Include hash algorithm identifier in fingerprint metadata
|
|
152
|
-
- Parse both old and new format during resume
|
|
153
|
-
- Migrate gracefully without data loss
|
|
154
|
-
|
|
155
|
-
## Configuration & Overrides
|
|
156
|
-
|
|
157
|
-
| Config | Default | Override |
|
|
158
|
-
|--------|---------|----------|
|
|
159
|
-
| `fingerprint_hash_algo` | "sha256" | "md5", "crc32" (performance mode only) |
|
|
160
|
-
| `truncated_fingerprint_len` | 16 | 8, 4, 0 (full hash) |
|
|
161
|
-
| `allow_drift_bypass` | false | Set to true for testing or known-good drift scenarios |
|
|
162
|
-
|
|
163
|
-
## Compliance & Audit
|
|
164
|
-
|
|
165
|
-
Every compressed summary must include:
|
|
166
|
-
```json
|
|
167
|
-
{
|
|
168
|
-
"fingerprint_at_compression": "fp_abc123def456",
|
|
169
|
-
"hash_algorithm": "sha256",
|
|
170
|
-
"truncated_length": 16,
|
|
171
|
-
"drift_detected": false,
|
|
172
|
-
"redaction_applied": false
|
|
173
|
-
}
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
This allows:
|
|
177
|
-
- Forensic reconstruction of environment at compression time
|
|
178
|
-
- Verification that no phantom data exists in compressed buffer
|
|
179
|
-
- Audit trail for compliance requirements (NIST, SOC2)
|
|
180
|
-
|
|
181
|
-
## Integration with Other Rules
|
|
182
|
-
|
|
183
|
-
- `rules/verification.md`: Fingerprint must be attached to all verification receipts
|
|
184
|
-
- `rules/runtime-guards.md`: Hash-based drift detection prevents credential exposure
|
|
185
|
-
- `commands/doctor.md`: Include fingerprint checks in the doctor workflow
|
|
186
|
-
|
|
187
|
-
---
|
|
188
|
-
|
|
189
|
-
**Status**: Active (enforcement: hard)
|
|
190
|
-
**Scope**: Global
|
|
191
|
-
**Created**: 2026-05-09T07:31:00Z
|
|
192
|
-
**Author**: agent (auto-generated via gap analysis)
|