Skip to content

docs: add core abstractions document#391

Open
gx-ai-architect wants to merge 1 commit into
mainfrom
docs/core-abstractions
Open

docs: add core abstractions document#391
gx-ai-architect wants to merge 1 commit into
mainfrom
docs/core-abstractions

Conversation

@gx-ai-architect
Copy link
Copy Markdown
Collaborator

Summary

  • Adds docs/abstractions.md — frames the Factory from first principles
  • Defines the two core primitives: The Loop (hypothesize → implement → measure → keep/revert → learn) and The Guardrails (auto-generated fitness function + non-overridable safety gates)
  • Maps all 57 modules to their role (loop state, loop execution, guardrails, learning, visualization, integration)
  • Classifies each as core (54%) vs optional (46%) with line counts
  • Documents the key implementation choices that are debatable vs stable

This is a companion to the existing architecture.md. That doc describes how things are implemented (three layers, state machine, data flow). This doc describes what the system is — useful for onboarding, investor conversations, and deciding where to experiment.

Test plan

  • Verify doc renders correctly on GitHub
  • Verify module list matches current codebase
  • Verify line counts are approximately correct

Generated with Claude Code

Frames the Factory from first principles — the two primitives
(Loop + Guardrails) that everything else derives from. Maps every
module to its role, classifies core vs optional, and documents
the key implementation choices that are debatable vs stable.

Companion to the existing architecture.md, which describes *how*
things are implemented. This doc describes *what the system is*.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@codecov
Copy link
Copy Markdown

codecov Bot commented May 27, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.31%. Comparing base (f9bd0ce) to head (fa1c198).

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #391   +/-   ##
=======================================
  Coverage   87.31%   87.31%           
=======================================
  Files          61       61           
  Lines        9339     9339           
=======================================
  Hits         8154     8154           
  Misses       1185     1185           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant