hermes - 💡(How to fix) Fix Proposal: record which SOUL version each kanban run executed under (provenance)

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

When a kanban task runs, there's currently no record of which SOUL.md the worker ran under. For reproducibility and auditing — "why did this run behave differently?" — it would help to capture the SOUL version on the run record.

Root Cause

  • prompt_builder.soul_version(home=None)sha256:<12hex> of the raw SOUL.md bytes; None when absent/empty (stable across unchanged SOUL → no churn).
  • A dedicated task_runs.soul_version column (added via the existing idempotent additive-migration path), not run metadata — because _end_run replaces run metadata wholesale at closure, a column is never clobbered and stays queryable.
  • The dispatcher resolves the tag once per spawn and reuses it for both the column stamp and a HERMES_SOUL_VERSION env export to the worker, so env and column are equal by construction. Stamp is idempotent (soul_version IS NULL guard). No behavior change for a profile with no SOUL.md (column stays NULL).

Fix Action

Fix / Workaround

  • prompt_builder.soul_version(home=None)sha256:<12hex> of the raw SOUL.md bytes; None when absent/empty (stable across unchanged SOUL → no churn).
  • A dedicated task_runs.soul_version column (added via the existing idempotent additive-migration path), not run metadata — because _end_run replaces run metadata wholesale at closure, a column is never clobbered and stays queryable.
  • The dispatcher resolves the tag once per spawn and reuses it for both the column stamp and a HERMES_SOUL_VERSION env export to the worker, so env and column are equal by construction. Stamp is idempotent (soul_version IS NULL guard). No behavior change for a profile with no SOUL.md (column stays NULL).
RAW_BUFFERClick to expand / collapse

Title: Proposal: record which SOUL version each kanban run executed under (provenance)

Summary

When a kanban task runs, there's currently no record of which SOUL.md the worker ran under. For reproducibility and auditing — "why did this run behave differently?" — it would help to capture the SOUL version on the run record.

Motivation

SOUL is the agent's primary identity/persona (loaded by prompt_builder.load_soul_md() from HERMES_HOME/SOUL.md). It can change over time and differs per profile. A long-lived board accumulates runs across SOUL edits with no way to attribute behavior to a specific SOUL revision. A small, stable provenance tag on each run closes that gap and pairs naturally with the existing per-run metadata.

Proposed approach (working branch exists)

I have this implemented on a branch and am happy to open a PR if you're open to the feature / approach:

  • prompt_builder.soul_version(home=None)sha256:<12hex> of the raw SOUL.md bytes; None when absent/empty (stable across unchanged SOUL → no churn).
  • A dedicated task_runs.soul_version column (added via the existing idempotent additive-migration path), not run metadata — because _end_run replaces run metadata wholesale at closure, a column is never clobbered and stays queryable.
  • The dispatcher resolves the tag once per spawn and reuses it for both the column stamp and a HERMES_SOUL_VERSION env export to the worker, so env and column are equal by construction. Stamp is idempotent (soul_version IS NULL guard). No behavior change for a profile with no SOUL.md (column stays NULL).

Open questions for maintainers

  1. Column on task_runs vs. a structured key in run metadata — preference?
  2. Hash-of-content vs. a user-managed semantic version string in SOUL.md (or support both)?
  3. Is exporting HERMES_SOUL_VERSION to the worker desirable, or column-only?

Happy to adjust the design before submitting a PR. Tests would accompany it.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING