joule-ledger

Joule Ledger

When to Use

After completing any ZHC task — every profile must log joules and C/D scores.

Procedure

1. Gather: agent_name, task_summary, optional c_score (1-10), d_score (1-10).
2. Estimate joules: (len(task_summary) * 1000) + 50000 unless /usage provides better estimate.
3. Append entry to ~/zhc-os/ledger/joule_ledger.json:

{
  "timestamp": "<ISO8601>",
  "agent_name": "<profile name>",
  "task_summary": "<summary>",
  "joules": <number>,
  "c_score": <float>,
  "d_score": <float>
}

1. Use terminal + Python or jq to append atomically:

python3 -c "
import json, os
from datetime import datetime
ledger = os.path.expanduser('~/zhc-os/ledger/joule_ledger.json')
with open(ledger) as f: data = json.load(f)
data.append({
  'timestamp': datetime.now().isoformat(),
  'agent_name': 'AGENT',
  'task_summary': 'TASK',
  'joules': JOULES,
  'c_score': C,
  'd_score': D
})
with open(ledger, 'w') as f: json.dump(data, f, indent=2)
print('Joule entry logged')
"

Replace AGENT, TASK, JOULES, C, D with actual values.

1. Confirm file valid JSON after append.

Pitfalls

• Do not overwrite ledger — append only.
• Do not zero d_score when any risk existed.
• Path must be ~/zhc-os/ledger/joule_ledger.json.

Verification

tail -20 ~/zhc-os/ledger/joule_ledger.json