Work in progress. This is the semantic and architectural governance repository for TradeForge.
This repository is the canonical shared knowledge system for TradeForge and its upstream Research Cockpit boundary — a structured cognition and decision system for discretionary trading workflows.
It is not the executable application and not the Research Cockpit implementation. The running system lives in the runtime repository:
The upstream research producer lives in the Research Cockpit repository:
TradeForge treats its own development as a replayable cognition system. This repository is the memory and governance layer that makes that possible.
It preserves:
- Ontology — what things mean in TradeForge (decisions, workspaces, personas, events, replays)
- Invariants — architectural truths that must never break
- Architectural doctrine — why the system is built the way it is
- Workflow semantics — how workflows behave and why
- UX philosophy — cognition-first, anti-dashboard interaction principles
- AI governance rules — what AI may and may not do inside the system
- Replay philosophy — how historical reconstruction should work
- Development memory — planning captures, implementation notes, processed knowledge
The separation exists by design. Code evolves quickly. Semantic meaning and architectural rationale should evolve deliberately. This repository is the deliberate layer.
Most projects embed architectural intent in code comments, Confluence pages, or ADRs that drift from reality. TradeForge takes a different approach:
- The knowledge base defines shared semantic doctrine, ontology, architecture meaning, and durable cross-repository boundary memory
- The runtime repository implements executable behavior, runtime planning, lifecycle authority, canonical events, and execution boundaries
- The Research Cockpit repository produces upstream evidence, provenance, research history, quality evaluation, and advisory submissions
- AI-assisted development sessions boot from this repository before writing any code
- Planning, implementation notes, and architectural observations are captured here and promoted through a knowledge stabilization process
This means:
- Future development sessions — including AI-assisted ones — can reconstruct architectural intent without reading code history
- Architectural drift is detectable and correctable by comparing the knowledge base against the implementation
- Semantic meaning is preserved even as implementation details change
| File | Purpose |
|---|---|
INVARIANTS.md |
Non-negotiable architectural and semantic truths |
SEMANTIC_BOOTSTRAP.md |
System worldview and operational initialization for AI-assisted development |
SEMANTIC_GOVERNANCE.md |
Rules for how knowledge stabilizes, promotes, and governs doctrine |
ARCHITECTURE.md |
Canonical architecture doctrine and layer ownership |
GLOSSARY.md |
Canonical terminology and semantic definitions |
UX_DOCTRINE.md |
Operational workspace and cognition philosophy |
EVENT_TAXONOMY.md |
Canonical event semantics and classifications |
EXECUTION_CONTRACT.md |
Rules for how AI-assisted development sessions must operate |
The progressive knowledge stabilization layer.
knowledge/
├── index/ Navigation, semantic entrypoints, context map
├── raw/ Unprocessed planning and implementation captures
├── processed/ Refined and synthesized knowledge
├── entities/ Canonical entity definitions (TradeIdea, ReplaySession, etc.)
├── topics/ Thematic syntheses (replayability, AI advisory, etc.)
└── outputs/ Temporary synthesis artifacts
Knowledge flows: raw → processed → entities/topics through deliberate promotion. Raw captures are not canonical. Entities are.
Operational governance systems and repeatable development workflows.
Key playbook: playbooks/development/runtime-kb-development-loop.md
This defines the canonical development workflow — how runtime implementation and knowledge base work stay synchronized across development sessions.
Reusable AI-assisted workflow entry points.
prompts/workflow/
├── runtime-planning.md Planning phase prompt
├── runtime-implementation.md Implementation phase prompt
├── kb-processing.md Knowledge stabilization prompt
└── operational-sync.md Roadmap/register sync prompt
These prompts operationalize the development loop in a reproducible way.
Behavioral reasoning constraints for AI-assisted sessions.
Skills define how to think — event sourcing discipline, lifecycle enforcement, replay integrity, workspace cognition. They are not procedures; they are reasoning constraints applied during development.
Canonical concept definitions — personas, lifecycle states, workspace semantics, market regimes, scenario structures, review artifacts.
When contradictions exist, authority resolves in this order:
INVARIANTS.md- Ontology definitions
- ADRs (in the runtime repository)
- Architecture doctrine
- Processed knowledge
- Raw notes and captures
Implementation must never silently redefine semantic meaning.
- Human decision sovereignty — the system assists, never decides
- Event ledger is canonical truth — all durable state derives from immutable events
- Replayability is foundational — all material workflows must support deterministic reconstruction
- AI is advisory only — AI may summarize, rank, and contextualize; it may never mutate canonical state, execute trades, or bypass lifecycle controls
- Workflow-centric, not CRUD-centric — the architecture optimizes for decision workflows, not generic entity management
See INVARIANTS.md for the full list.
| Repository | Owns | Does not own |
|---|---|---|
| TradeForge-KnowledgeBase | Shared semantic doctrine, ontology and architecture meaning, governance, durable cross-repository boundary memory | Runtime implementation, local Cockpit internals, lifecycle state |
| TradeForge | Executable runtime, runtime implementation planning, accepted import contracts, lifecycle services, canonical events, execution boundaries | Shared ontology, Cockpit source processing |
| TradeForge-ResearchCockpit | Upstream evidence and research production, source provenance, research history, quality evaluation, advisory submission production, optional TradeForge-compatible projections | Lifecycle authority, canonical Event Ledger state, approval, execution, runtime planning |
When contradictions arise, the knowledge base is authoritative for shared semantic meaning, TradeForge is authoritative for accepted runtime behavior and canonical lifecycle state, and Research Cockpit is authoritative for its local research-production implementation.
Research Cockpit context is bounded. Activate it only for research-production, advisory-handoff, import-boundary, or cross-repository governance work.
The knowledge base has been reconciled against the runtime through the 2026-07-27 sync pass. Runtime implementation has advanced past M14 into M14C, the Evidence Density slice of M-EZ, and the M-RF API boundary decomposition.
Current runtime-aligned state:
- M14 Behavioral Intelligence and Cognitive Auditability is complete.
- M14C advisory import mediation is implemented for Thesis and Plan workflows through TF-R001 and TF-R002.
- EV-00 through EV-05 are implemented: evidence authority, scheduled snapshot refresh, watchlist, transparent attention ranking, per-symbol evidence, and charting.
- M-RF backend API route decomposition is complete.
- GOV-03 is complete in the runtime repository: GitHub Spec Kit is installed as a prospective SDD layer with a TradeForge-specific constitution and workflow guide. SDD artifacts remain subordinate to KB doctrine, ADRs, issue discipline, and milestone governance.
- M-RF-FE, M-RF2, M-PT, and the remaining M-EZ ramp/governance work are planned.
Ongoing work: ontology promotion, topic synthesis, playbook evolution, and explicit sync passes whenever runtime implementation changes durable semantic or governance meaning.
This is a solo architectural project. The knowledge base is public for transparency — to show how a semantic governance layer can work alongside a runtime codebase, and what AI-assisted architecture discipline looks like in practice.
Questions and observations are welcome via issues on the runtime repository.
TradeForge — structured cognition for discretionary trading.