Skip to content

Codebase Taxonomy

This page defines how the repo should classify code surfaces.

The point is simple: not every file deserves the same status, and the repository should say that explicitly instead of flattening everything into one vague bucket.

Classification Thresholds

Core

A file is Core if it defines DDA-X mechanics, runtime behavior, memory, provider logic, configuration, or the main public execution surface.

Examples:

  • src/llm/*
  • src/memory/*
  • src/discord_agent/*
  • run_discord_agent.py
  • run_snake.ps1

Lineage

A file is Lineage if it belongs to the documented historical arc of DDA-X development captured in the simulation chronology.

Primary references:

Branch

A file is a Branch if it is a serious DDA-X experiment or world-specific build that extends the framework, but is not currently part of the documented chronology.

Applied

A file is Applied if it turns DDA-X into a companion, chatbot, UI, or domain-specific user-facing system.

Stable applied surfaces can live under apps/ instead of simulations/ when they deserve to stand as first-class software rather than experimental drafts.

Support

A file is Support if it exists to analyze runs, compare outputs, automate tests, export artifacts, or debug integrations.

Legacy Local

A file is Legacy Local if it was created for one-off debugging or machine-specific inspection and is kept only as preserved scratch history. These files should not dominate the repo surface.

Current Structure

Core

  • src/llm/openai_provider.py
  • src/llm/hybrid_provider.py
  • src/memory/ledger.py
  • src/discord_agent/config.py
  • src/discord_agent/runtime.py
  • src/discord_agent/bot.py
  • run_discord_agent.py
  • run_snake.ps1
  • configs/discord_agent/*.json

Lineage

All files listed in:

  • simulation_chronology.csv

That documented lineage remains the canonical historical arc even though the working simulations/ directory has grown beyond it.

Branch

These are substantial DDA-X branches that deserve to be treated as real experiments rather than random leftovers:

  • simulations/clock_that_eats_futures.py
  • simulations/eternal_return.py
  • simulations/flame_war.py
  • simulations/glass_cathedral.py
  • simulations/harborlight.py
  • simulations/lighthouses_kestrel_bay.py
  • simulations/parenting_clash_ddax_v2.py
  • simulations/parenting_clash_azure_phi.py
  • simulations/simulate_soul_mirror.py
  • simulations/sonnet_gpt52_collab.py

Applied

These are domain-facing or character-facing builds of the framework:

  • apps/brobot/true_brobot.py
  • apps/brobot/brobot_ui.py
  • apps/eckhart/azure_phi_chat.py
  • apps/eckhart/eckhart_terminal.py
  • apps/mad_hatter/mad_hatter_chatbot.py
  • apps/repository_guardian/repository_guardian.py
  • apps/singularity/singularity_chatbot.py
  • apps/torahbot/torah_study_bot.py
  • apps/torahbot/torahbot_ui.py

Support

These files support analysis, testing, comparison, or operational inspection:

  • scripts/session_tools/analyze_flame_war.py
  • scripts/session_tools/repository_guardian_dashboard.py
  • scripts/simulation_support/repository_guardian_stress_test.py
  • scripts/simulation_support/torahbot_debug_renderer.py
  • scripts/simulation_support/verify_clock_that_eats_futures.py
  • scripts/debug_api/legacy/debug_model.py
  • scripts/vanilla_comparison.py
  • scripts/debug_api/openai_probe.py
  • scripts/session_tools/*

Legacy Local

These older one-off OpenAI probes are preserved under:

  • scripts/debug_api/legacy/*

They are no longer front-of-repo surfaces. The consolidated replacement is:

  • scripts/debug_api/openai_probe.py

Practical Rule

When deciding whether a file belongs at the public front of the repo:

  • Core and Applied deserve strong visibility
  • Lineage deserves documentation and historical framing
  • Branch deserves categorization, not burial
  • Support belongs under scripts/ or explicit utility sections
  • Legacy Local should stay out of the repo root and out of the main narrative

Experimental Families

The non-lineage experimental surface already falls into recognizable families.

Pressure and Fracture

  • simulations/flame_war.py
  • simulations/parenting_clash_ddax_v2.py
  • simulations/parenting_clash_azure_phi.py
  • simulations/sonnet_gpt52_collab.py

These are social-stress and facilitation experiments: escalation, repair, blame, empathy, rigidity, and healing under conflict.

Mythic and Narrative Branches

  • simulations/clock_that_eats_futures.py
  • simulations/eternal_return.py
  • simulations/glass_cathedral.py
  • simulations/lighthouses_kestrel_bay.py
  • simulations/simulate_soul_mirror.py

These push DDA-X into richer symbolic, metaphysical, or world-driven settings while still testing identity, pressure, drift, and recovery.

Companion and Character Systems

  • apps/brobot/true_brobot.py
  • apps/eckhart/azure_phi_chat.py
  • apps/eckhart/eckhart_terminal.py
  • apps/mad_hatter/mad_hatter_chatbot.py
  • apps/repository_guardian/repository_guardian.py
  • apps/singularity/singularity_chatbot.py
  • apps/torahbot/torah_study_bot.py
  • simulations/harborlight.py

These are more directly user-facing builds where DDA-X becomes a persona, teacher, companion, or character system.

Interfaces and Support Surfaces

  • apps/brobot/brobot_ui.py
  • apps/torahbot/torahbot_ui.py
  • scripts/session_tools/analyze_flame_war.py
  • scripts/session_tools/repository_guardian_dashboard.py
  • scripts/simulation_support/repository_guardian_stress_test.py
  • scripts/simulation_support/torahbot_debug_renderer.py
  • scripts/simulation_support/verify_clock_that_eats_futures.py
  • scripts/debug_api/legacy/debug_model.py

These are wrappers, dashboards, inspection tools, and validation helpers around the main experiments.