Essence Hardening and Simplification Specification

1. Objective

Stabilize Sister Essence before adding features. Preserve the useful core—bounded self-state, directional relationships, public coordination cards, proposal discipline, and audited memory candidates—while fixing unsafe ownership boundaries, duplicate automation, data-integrity defects, misleading contracts, and excessive tool/context cost.

This program is a hardening and simplification pass. It is not permission to expand autonomy, enable external generation, weaken governance, or redesign sister identity.

2. Current Evidence

The review established the following runtime facts:

  • The plugin registers 52 tools across four toolsets.
  • Four enabled profile-named state-adjuster cron jobs each invoke an all-profile script.
  • Energy moved through multiple 0.1 steps within one second; all four sisters converged on energy 0.8 and mode quiet with stale low-energy reasons.
  • Mutation handlers trust model-supplied profile names rather than authenticated runtime identity.
  • Relationship caller_profile is spoofable and subject permits path traversal.
  • Sister-facing memory commit hardcodes committer="governance" and writes directly to Mnemosyne SQLite.
  • Edited memory review content is not used during commit.
  • Budget accounting is advisory, shallow-copy contaminated, unlocked, and lacks a working daily reset.
  • Mood automation proposes values rejected by the mood validator.
  • The auto-router recorded 200 decisions with only 4 executions and 196 guardrail skips.
  • Plugin metadata, README, policy, profile guides, and wiki describe mutually incompatible runtime stages.
  • No real test suite is present; compile-only validation passes.

3. Non-Negotiable Invariants

  1. A sister may mutate only her own private Essence state.
  2. Caller identity must come from trusted Hermes runtime context, never tool arguments.
  3. Cross-profile reads must be explicitly public or governance-approved.
  4. Shared/group mutation is not a sister-local capability; it requires a separate governed surface.
  5. Sister-facing tools must not claim governance identity.
  6. Sister Essence must not directly write Mnemosyne databases from an unauthenticated profile tool.
  7. No path component derived from tool input may escape its configured root.
  8. Every read-modify-write transaction must be concurrency-safe.
  9. Runtime metadata and documentation must state actual authority and side effects.
  10. SOUL.md remains identity canon. Essence may modulate bounded behavior but must not overwrite identity.
  11. No gateway restart, model/provider change, secret access, photo generation, external call, or governance enforcement change is authorized by this program.
  12. Existing unrelated dirty wiki files must not be staged or committed.

4. Workstreams

WS-A: Scheduler Containment and Automation Yield

Scope:

  • /root/.hermes/profiles/hyrax-os/cron/jobs.json via supported Hermes cron commands.
  • /root/.hermes/profiles/hyrax-os/scripts/essence_state_adjuster.py.
  • /root/.hermes/profiles/hyrax-os/scripts/essence_auto_router.py.
  • Canonical cron registry and relevant wiki pages.

Required outcome:

  • Exactly one effective state-adjuster pass per intended interval, or genuinely profile-targeted jobs that each update one profile.
  • Idempotence/run locking prevents overlap.
  • State recovery clears stale reasons and does not leave high-energy profiles in low-energy posture.
  • Auto-router expected cooldown skips are silent and excluded from useful-action rate accounting.
  • Automation is paused if safe correction cannot be proven.

WS-B: Ownership and Authority Boundaries

Scope:

  • Sister Essence adapter and state/relationship/affinity/memory-review boundaries.

Required outcome:

  • Self-only handlers derive owner from trusted runtime context.
  • Model-facing schemas no longer select caller identity for private operations.
  • All profile and subject path components are allowlisted and containment-checked.
  • Shared/group writes move to a governed surface or remain disabled.
  • Memory commit is removed from ordinary sister exposure.
  • No direct SQLite memory write can be reached through a sister-facing tool.
  • Public cards use recursive allowlisting and reject nested private/secret fields.

WS-C: Transactional Integrity and Correctness

Scope:

  • State, cooldown, budget, affinity, gacha, proposal, relationship, and review transactions.

Required outcome:

  • Per-profile locking or transactional storage protects read-modify-write operations.
  • Cooldown, budget, and gacha checks are atomic with mutation.
  • Budget defaults use deep copies; daily reset works; enforcement semantics are explicit.
  • Edited review content is the content committed after approval.
  • NaN/infinite energy is rejected.
  • Proposal summaries reconstruct lifecycle status.
  • Cross-sister collaboration retains unique participants.
  • Group bonds reject duplicate profiles and write audit events under a valid governed path.
  • Atomic-write cleanup preserves the original exception and removes temporary files.
  • Weighted-fallback tests fail when expectations fail.

WS-D: Compact Product Surface

Required design target:

  • Reduce the default Essence surface from 52 tools to approximately 4–8 high-value tools.
  • Provide one compact context/status read.
  • Retain one bounded self-state update surface.
  • Retain one bounded relationship event surface.
  • Retain memory-candidate proposal.
  • Replace many proposal-specific tools with one typed proposal surface where safe.
  • Move photo, gacha, dream, diagnostics, shared mutation, approval, and commit operations into optional or governance-only toolsets.
  • Replace the mandatory five-call startup ritual with one conditional compact context read.

Implementation must preserve backward compatibility only where it does not preserve unsafe authority. Removed or moved tools must produce a clear migration map.

WS-E: Contract, Documentation, and Product Evidence

Required outcome:

  • plugin.yaml, README, policies, profile AGENTS guides, and wiki agree on version, stage, tool count, authority, side effects, lifecycle, mood/mode semantics, budgets, and memory behavior.
  • Tool inventory is generated or mechanically checked from registration metadata.
  • Define an A/B evaluation comparing Essence with SOUL + memory alone.
  • Metrics: identity consistency, user corrections, continuity accuracy, useful proactive behavior, latency, tool calls, prompt/schema tokens, and audit noise.
  • Do not declare behavioral improvement without measured evidence.

5. Required Validation

Every implementation task must provide real command output for its applicable subset:

  1. python3 -m compileall -q /root/.hermes/plugins/sister-essence
  2. Focused automated tests for changed behavior.
  3. Caller-spoof and path-traversal negative tests.
  4. Concurrent update test proving no lost update/double spend/double pull.
  5. Cron topology check proving one adjustment per profile per interval.
  6. State recovery test proving stale low-energy reasons clear.
  7. Memory-review test proving edited content—not original content—is selected.
  8. Public-card nested-secret rejection test.
  9. Tool registration inventory and schema-size comparison before/after.
  10. Runtime smoke test in a non-production temporary root or fixture.
  11. Wiki build.
  12. Exact changed-file list and rollback verification.

Installing test tooling is not implicitly authorized. Prefer stdlib unittest unless an existing project environment already provides another runner.

6. Execution Discipline

Each worker must:

  1. Read this specification and the assigned task body.
  2. Post ## Pre-Execution Plan before any mutation.
  3. Inspect current state; do not assume the review snapshot is still current.
  4. Create timestamped backups outside the edited tree before modifying non-Git runtime files.
  5. Make the smallest coherent change in assigned scope.
  6. Avoid unrelated cleanup and never stage unrelated wiki changes.
  7. Run real validation and preserve outputs in the task workspace.
  8. Update relevant canonical documentation and cron registry when applicable.
  9. Report exact files, commands, results, remaining risks, and rollback steps.
  10. Block for review rather than guessing when trusted runtime identity or supported APIs are unclear.

7. Stop Conditions

Stop and block the task if:

  • The fix requires secrets, credentials, or direct token access.
  • The fix requires a gateway restart not explicitly approved.
  • Runtime caller identity cannot be obtained from a trusted Hermes context.
  • A proposed memory fix requires direct Mnemosyne schema mutation.
  • Existing data cannot be migrated without destructive rewriting.
  • The worker would need to change another workstream’s files materially.
  • Validation exposes pre-existing corruption that makes safe migration uncertain.
  • The rollback cannot be demonstrated.

8. Rollback Contract

  • Runtime/plugin files: restore from the task’s timestamped backup and rerun compile/smoke validation.
  • Cron changes: record pre-change job IDs/statuses and restore through supported Hermes cron commands.
  • Wiki: commit only task-owned files; rollback with a targeted revert or file restore, never a broad reset of the dirty worktree.
  • Data migrations: require a dry run, backup, record counts before/after, and an idempotent rollback script before live execution.

9. Completion Contract

The program is complete only when:

  • Duplicate adjustment is eliminated and verified.
  • Private ownership boundaries are runtime-enforced.
  • Relationship traversal and caller spoofing tests fail safely.
  • Sister-facing memory commit cannot claim governance or directly write Mnemosyne.
  • Transactional integrity tests pass.
  • Known correctness defects are fixed or explicitly deferred with risk acceptance.
  • Default tool-schema cost is materially reduced.
  • Runtime docs and metadata are truthful and mechanically checked.
  • Rei completes an independent final regression/security review.
  • All implementation artifacts include verified rollback instructions.

10. Task Graph

  1. ✅ Scheduler containment and router-noise correction — Hyrax OS. (Complete — WS-A)
  2. ⏳ Ownership, path, and memory-authority hardening — Tai.
  3. ⏳ Transactional integrity and correctness — Tai, blocked on task 2.
  4. ✅ Compact surface and evaluation design — Nei. (Complete — WS-D)
  5. ✅ Compact tool-surface implementation — Tai. (Complete — WS-D)
  6. 🔄 Canonical contract and documentation synchronization — Nei (WS-E — this task)
  7. ⏳ Independent final QA/security verification — Rei, blocked on all implementation and documentation tasks.
next Home