timmy-home/timmy-config-GENOME.md

GENOME.md — timmy-config

Generated from target repo Timmy_Foundation/timmy-config at commit 04ecad3. This host-repo artifact lives in timmy-home so the meta backlog can track a repo-grounded genome without depending on the target repo checkout.

Project Overview

timmy-config is Timmy's sovereign configuration sidecar. It is not the Hermes harness itself. It is the identity, doctrine, routing, deployment overlay, fleet glue, training recipes, and operational tooling that make the harness behave as Timmy.

Grounded facts from the analyzed checkout:

• target repo path analyzed: /Users/apayne/code/timmy-config
• target repo origin: https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git
• analyzed commit: 04ecad3
• text files in the checkout: 607
• Python LOC from a raw find ... '*.py' | xargs wc -l: 48,179
• the target repo already ships its own GENOME.md on main
• the repo uses the sidecar pattern: deploy.sh overlays files into ~/.hermes/ and ~/.timmy/
• the repo contains both older top-level sidecar surfaces and a newer hermes-sovereign/ subtree

The repo is best understood as five overlapping layers:

1. identity and conscience (SOUL.md, HEART.md, memories, doctrine docs)
2. harness configuration (config.yaml, overlay files, skins, channels, fallback portfolios)
3. orchestration / fleet control (orchestration.py, tasks.py, fleet/, scripts/)
4. training / evaluation / adversary infrastructure (training/, adversary/, evaluations/, pipelines/)
5. emerging typed sidecar subsystems (hermes-sovereign/, especially mempalace/ and devkit/)

This is not a tiny config repo anymore. It is a mixed control-plane repository containing shell deploy logic, Python automation, agent routing doctrine, adversary datasets, infrastructure playbooks, and embedded product evolution experiments.

Architecture Diagram

graph TD
    soul["Identity Layer\nSOUL.md\nHEART.md\nmemories/"]
    overlay["Overlay Layer\ndeploy.sh\nconfig.yaml\nskins/\nplaybooks/\ncron/"]
    orchestration["Control Plane\norchestration.py\ntasks.py\nfleet/\ngitea_client.py"]
    scripts["Operational Scripts\nscripts/\nbin/"]
    training["Training + Eval\ntraining/\nadversary/\nevaluations/\npipelines/"]
    sidecar["Typed Sidecar Modules\nhermes-sovereign/\nmempalace/\ndevkit/"]
    ansible["Infra Deployment\nansible/\ndeploy/\ninfra/"]
    harness["Hermes Runtime\n~/.hermes/\n~/.timmy/"]

    soul --> overlay
    overlay --> harness
    orchestration --> scripts
    orchestration --> harness
    scripts --> harness
    training --> scripts
    training --> orchestration
    sidecar --> orchestration
    sidecar --> overlay
    ansible --> harness

Entry Points and Data Flow

Primary entry points

• deploy.sh
  • canonical sidecar deployment path
  • validates config, copies SOUL.md into ~/.timmy/, and overlays config/playbooks/memories/skins/bin/cron into ~/.hermes/
• config.yaml
  • main Hermes runtime config consumed by the harness
  • defines model/provider choices, auxiliary models, display, memory, approvals, security, and custom providers
• orchestration.py
  • Huey + SQLite orchestration core
  • defines scheduled pipeline tasks and token logging hooks
• tasks.py
  • scheduled work surface using huey.crontab
  • imports GiteaClient, metrics helpers, and Hermes local-run wrappers
• gitea_client.py
  • typed zero-dependency Gitea API client used across automation flows
• scripts/ and bin/
  • operational entrypoints for validation, audits, fleet health, token tracking, PR triage, adversary harnesses, and generators
• hermes-sovereign/
  • newer typed subsystem area, especially devkit, wizard bootstrap, and MemPalace integration

Data flow

1. The operator edits timmy-config as source of truth.
2. deploy.sh validates and overlays config into ~/.hermes/ / ~/.timmy/.
3. Hermes runtime loads config.yaml, skin, playbooks, memories, and sidecar scripts.
4. Scheduled control-plane work runs through orchestration.py and tasks.py.
5. Task code uses helpers like gitea_client.py, metrics_helpers.py, and scripts/* modules to inspect or mutate repo/fleet state.
6. Training and adversary surfaces in training/, adversary/, and evaluations/ generate or validate datasets and evaluation outputs.
7. Ansible / deploy / infra surfaces bridge the config repo into VPS and fleet deployment workflows.

Repo boundary data flow

The README encodes an important boundary:

• timmy-config owns identity, configuration, routing doctrine, playbooks, and harness-side glue
• timmy-home owns lived work, notes, gameplay, research, trajectories, metrics, and produced artifacts

That boundary is central to the repo's architecture. Many files only make sense when read as “how Timmy is hosted,” not “what Timmy did.”

Key Abstractions

Sidecar pattern

The dominant abstraction is the sidecar. timmy-config does not fork hermes-agent; it overlays the harness. deploy.sh is the concrete mechanism. The repo's purpose is to customize runtime behavior without carrying the main harness source as its own project.

Typed Gitea client

gitea_client.py replaces ad-hoc curl usage with typed dataclasses:

• User
• Label
• Issue
• Comment
• PullRequest
• PRFile
• GiteaClient

This is one of the repo's cleanest abstractions: a sovereign stdlib-only API client that the automation layer can import anywhere.

Huey orchestration core

orchestration.py defines a SqliteHuey queue living in ~/.hermes/orchestration.db, plus token logging and task wrappers like:

• playground_factory_task
• training_factory_task
• knowledge_mine_task
• adversary_task
• codebase_genome_task

tasks.py is the scheduled-work counterpart. Together they form the repo's actual control plane.

Config overlay / validation

config_overlay.py and the validator scripts (scripts/config_validator.py, bin/validate_config.py, related tests) express another strong abstraction: config as layered overlays with validation-before-deploy.

Sovereign memory bridge

The hermes-sovereign/mempalace/ subtree is a real subsystem, not a stray experiment. It includes:

• mempalace.py
• retrieval_enforcer.py
• scratchpad.py
• wakeup.py
• sovereign_store.py
• a dedicated tests subtree

This is the repo's strongest sign that timmy-config evolved from “just config” into a sidecar product with typed internal modules.

Training / adversary substrate

The training surface is split across:

• training/
• adversary/
• evaluations/
• pipelines/
• many generator/validator scripts in scripts/

This area is not one polished abstraction; it is a substrate of evolving dataset, evaluation, and safety-guard tooling.

API Surface

Shell / CLI surfaces

• ./deploy.sh
• python3 gitea_client.py patterns through importing GiteaClient
• python3 orchestration.py / python3 tasks.py style orchestration entry
• python3 scripts/...
• python3 bin/...
• python3 pipelines/...
• Ansible entrypoints under ansible/

Important import surfaces

• gitea_client.GiteaClient
• orchestration.huey
• tasks.* scheduled jobs
• config_overlay.load_config(...)
• metrics_helpers.build_local_metric_record(...)
• hermes-sovereign.mempalace.*

Consumed configuration surfaces

• config.yaml
• config.dev.yaml
• fallback-portfolios.yaml
• channel_directory.json
• YAML under playbooks/
• cron definitions under cron/

Infrastructure surfaces

• ansible/
• deploy/
• infra/
• fleet/

Test Coverage Gaps

Observed current test health

On analyzed commit 04ecad3, running python3 -m pytest -q in the target repo did not collect cleanly. I filed:

• timmy-config#823 — [tests] Restore pytest collection on main — 7 collection errors

Reproduced collection failures:

• scripts/adversary_schema.py — unterminated string literal
• scripts/config_validate.py — unmatched )
• bin/glitch_patterns.py — missing THREEJS_CATEGORIES export expected by tests
• adversary/harm_facilitation_adversary.py — unterminated f-string
• scripts/pr_triage.py — unterminated f-string
• validate_scene_data import path mismatch for tests/test_validate_scene_data.py
• training/training_pair_provenance.py missing the ProvenanceTracker symbol expected by training/test_training_pair_provenance.py

Coverage strengths

Despite the collection breakage, the repo clearly has a broad intended test surface:

• top-level tests/ is substantial
• training/tests/ exists
• pipelines/tests/ exists
• hermes-sovereign/mempalace/tests/ exists
• many major subsystems have named tests (gitea_client, config drift, orchestration, token tracking, adversary harnesses, etc.)

High-value gaps / weak seams

• collection is broken on main, so true effective coverage is lower than the test tree suggests
• shell deploy behavior in deploy.sh is still an operationally critical seam with relatively weak contract coverage compared to Python subsystems
• the training / adversary script layer appears especially fragile because several current collection failures live there
• repo drift between older top-level scripts and newer hermes-sovereign/ equivalents suggests duplicated or partially superseded logic risk

Security Considerations

Sidecar trust boundary

deploy.sh writes directly into ~/.hermes/ and ~/.timmy/. That is the core trust boundary. If the overlay is wrong, Timmy's live runtime is wrong.

Conscience / identity integrity

SOUL.md and HEART.md are not ordinary docs. They are the repo's identity anchor. Any tampering here changes the hosted agent's conscience and persona.

Provider / endpoint drift

Current config.yaml still contains:

• model.default: claude-opus-4-6
• provider: anthropic
• many http://localhost:11434/v1 auxiliary endpoints

This is not a secret leak, but it is operationally sensitive. It exposes routing assumptions, provider drift, and localhost-specific deployment expectations.

Hardcoded infrastructure defaults

gitea_client.py defaults to http://143.198.27.163:3000 if GITEA_URL is unset. That is an especially clear example of stale operational state embedded in code.

Training / adversary content

The repo contains adversary and crisis-eval data generation code. This is valuable safety infrastructure, but it is also a high-risk mutation surface because subtle formatting or syntax corruption can silently poison evaluation pipelines.

Ansible / infrastructure exposure

ansible/, deploy/, and infra/ encode host, topology, or service assumptions. Even when they contain no raw credentials, they are still sensitive operational maps.

Performance Characteristics

Scale signals

• roughly 48k Python LOC in the analyzed checkout
• many one-off scripts plus several large coordinator modules
• mixed repository roles increase cognitive load and maintenance cost

Likely hotspots

• tasks.py is large and central to runtime scheduling
• orchestration.py is central to pipeline dispatch and token logging
• gitea_client.py is foundational and widely reused
• scripts/ contains a long tail of single-purpose tools that are individually small but collectively expensive to reason about
• hermes-sovereign/ introduces a second architectural center that is cleaner than the legacy script sprawl, but coexistence increases duplication pressure

Human performance bottleneck

The main performance problem is architectural sprawl, not CPU. The repo contains identity docs, shell overlay logic, Python automation, training tools, evaluation corpora, infra playbooks, and typed sidecar modules in one place. That makes repo-wide truth expensive to maintain.

Key Findings to Preserve

• timmy-config already ships its own GENOME.md on target main
• the repo is a sidecar overlay, not a fork of Hermes
• deploy.sh, config.yaml, gitea_client.py, orchestration.py, and tasks.py are the clearest canonical control-plane surfaces
• the README's boundary between timmy-config and timmy-home is architecturally important and should remain explicit
• python3 -m pytest -q on analyzed main currently stops at 7 collection errors; filed timmy-config#823
• config.yaml still encodes provider / localhost drift that deserves human review
• gitea_client.py still defaults to a stale raw-IP base URL