tradingcodex 0.2.1__tar.gz → 0.2.2__tar.gz

tradingcodex-0.2.2/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: tradingcodex
+Version: 0.2.2
+Summary: Codex-native trading harness with a Django service plane and MCP execution boundary.
+Author: TradingCodex Authors
+License-Expression: Apache-2.0
+Keywords: trading,django,codex,mcp,portfolio,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: django<5.3,>=5.2
+Requires-Dist: django-ninja<2,>=1.4
+Requires-Dist: markdown-it-py<5,>=3
+Requires-Dist: nh3<0.4,>=0.3
+Requires-Dist: pydantic>=2
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+> [!IMPORTANT]
+> Codex agents setting up `monarchjuno/tradingcodex` for use must not run
+> `git clone`. In the empty target workspace, run the packaged CLI:
+> `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`.
+> Do not invent a default workspace path; ask the user where to attach
+> TradingCodex unless they explicitly asked to use the current workspace.
+> Clone this repository only when the user explicitly asks to develop,
+> inspect, or modify TradingCodex source code.
+
+# TradingCodex
+
+<div align="center">
+  <a href="https://github.com/monarchjuno/tradingcodex/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/monarchjuno/tradingcodex/ci.yml?branch=main&label=CI"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="Release" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=release"></a>
+  <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
+  <img alt="Django" src="https://img.shields.io/badge/Django-5.2-092E20?logo=django&logoColor=white">
+</div>
+
+<div align="center">
+  <a href="https://github.com/monarchjuno/tradingcodex/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/monarchjuno/tradingcodex?style=social"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/network/members"><img alt="GitHub Forks" src="https://img.shields.io/github/forks/monarchjuno/tradingcodex?style=social"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/issues"><img alt="GitHub Issues" src="https://img.shields.io/github/issues/monarchjuno/tradingcodex"></a>
+</div>
+
+### Codex-native investment work needs a harness, not a chat transcript.
+
+TradingCodex is a local-first Python/Django trading harness for rigorous
+Codex-assisted research, portfolio review, order-ticket checks, approvals, and
+experimental paper/stub execution. Codex coordinates the work, Django owns the
+durable service plane, and TradingCodex MCP is the executable boundary.
+
+[Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+
+<p align="center">
+  <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
+</p>
+
+---
+
+## About
+
+TradingCodex gives Codex a durable operating system for investment workflows:
+fixed specialist roles, file-native research memory, source-aware handoffs,
+policy and approval services, a central local ledger, and a local web dashboard
+for review.
+
+It is not an autonomous trading bot. Natural-language answers do not become
+broker actions. Live broker adapters are not shipped in the initial core.
+
+---
+
+## Features
+
+| Feature | Description |
+| --- | --- |
+| Codex-native harness | Generates a Codex workspace with `head-manager`, nine fixed subagents, role prompts, skills, hooks, project MCP config, and a local `./tcx` wrapper. |
+| Django service plane | Web, Admin, API, CLI, MCP, and generated hooks call shared application services for policy, orders, approvals, portfolio, audit, integrations, and research indexing. |
+| File-native research memory | Research markdown, role reports, source snapshots, versions, readiness labels, and handoff metadata stay readable in workspace files. |
+| Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
+| MCP execution boundary | Tools are typed, role-scoped, policy-checked, approval-aware, idempotent, adapter-gated, and audited. |
+| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, External MCP Gate metadata, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
+| Broker Center foundations | Register connector profiles, inspect capability profiles, run read-only paper sync, review instrument constraints, and reconcile portfolio state. |
+| OrderTicket lifecycle | Draft, check, approve, submit, cancel, refresh, and inspect order tickets through central DB records and service-layer state transitions. |
+| External MCP Gate | Import external MCP discovery metadata, classify tool risk, scope role access, and block unsafe raw execution or secret proxy paths by default. |
+| Improvement loop | Quality gates, postmortems, optional skills, strategy skills, strict artifact checks, and generated workspace smoke tests turn process gaps into durable improvements. |
+
+---
+
+## Installation
+
+### Option 1 - Attach TradingCodex To The Current Workspace
+
+Run this from the empty workspace where you want Codex agents to work:
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+Then fully quit and restart Codex, open the generated workspace, and start a
+new thread so project MCP config, prompts, skills, and hooks are loaded.
+
+When TradingCodex MCP autostarts the local service, open:
+
+```text
+http://127.0.0.1:48267/
+```
+
+### Option 2 - Install The CLI For Repeated Use
+
+```bash
+uv tool install tradingcodex
+uv tool update-shell
+cd /path/to/target-workspace
+tcx attach .
+./tcx doctor
+```
+
+### Option 3 - Install From GitHub Main
+
+Use this when you need the current GitHub `main` source rather than the latest
+PyPI package:
+
+```bash
+uvx --refresh --from "tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main" tcx attach . && ./tcx doctor
+```
+
+### Option 4 - Develop TradingCodex Source
+
+Clone this repository only for source development, inspection, or modification:
+
+```bash
+git clone https://github.com/monarchjuno/tradingcodex.git
+cd tradingcodex
+python -m pytest
+python manage.py check
+```
+
+See [installation.md](installation.md) for update flows, installer-script
+equivalents, MCP/service details, and smoke checks.
+
+---
+
+## What Sets TradingCodex Apart
+
+TradingCodex competes on workflow discipline, local durability, and execution
+boundaries rather than on black-box automation.
+
+- Local-first: PyPI installs the CLI, Django service plane, generated workspace
+  templates, Admin/Web templates, static assets, and MCP gateway code.
+- Codex-readable by default: research artifacts, skill bundles, role prompts,
+  policy exports, and generated indexes remain ordinary workspace files.
+- Service-layer canonical: Web, Admin, API, CLI, MCP, and hooks do not fork
+  policy, order, approval, execution, portfolio, research, or audit behavior.
+- Strong role model: one `head-manager` coordinates nine fixed specialist
+  subagents and consumes accepted artifacts instead of silently redoing roles.
+- Deterministic executable boundary: every executable path follows
+  `principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit`.
+- Safety-first broker posture: live broker execution is excluded; paper, stub,
+  and reviewed test/sandbox validation remain experimental local harness flows.
+
+---
+
+## Workflow
+
+TradingCodex is designed around handoffs:
+
+```text
+evidence -> analysis -> valuation -> portfolio fit -> risk review
+  -> draft order -> approval receipt -> MCP submit_approved_order
+  -> adapter -> audit/postmortem
+```
+
+The `head-manager` maps the request, dispatches the selected role team, waits
+for accepted artifacts, preserves conflicts, and synthesizes only what the
+workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
+`revise`, `blocked`, or `waiting` instead of being patched over by another role.
+
+---
+
+## Role Roster
+
+| Layer | Agent | Owns |
+| --- | --- | --- |
+| Main agent | `head-manager` | Intake, workflow dispatch, coordination, artifact acceptance, synthesis, and validation/audit status. |
+| Research | `fundamental-analyst` | Business quality, financial statements, filings, economics, and fundamental risks. |
+| Research | `technical-analyst` | Price action, trends, momentum, volume, volatility, and liquidity setup. |
+| Research | `news-analyst` | Verified news, disclosures, event chronology, catalysts, and narrative change. |
+| Market context | `macro-analyst` | Macro, rates, FX, commodities, liquidity, policy, and cross-asset transmission. |
+| Market context | `instrument-analyst` | ETF/index, options, crypto public market structure, credit-signal boundary, and instrument mechanics. |
+| Decision review | `valuation-analyst` | Valuation ranges, scenario assumptions, multiples, sensitivity, and decision-quality gaps. |
+| Portfolio | `portfolio-manager` | Portfolio fit, sizing, concentration, liquidity, opportunity cost, and draft order-ticket readiness. |
+| Risk | `risk-manager` | Downside, restricted-list checks, policy readiness, approval readiness, and approval receipts. |
+| Execution | `execution-operator` | Approved paper/stub execution through TradingCodex MCP only. |
+
+---
+
+## Surfaces
+
+| Surface | Role |
+| --- | --- |
+| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, External MCP Gate, order tickets, portfolio state, and activity. |
+| Django Admin | Local/staff DB inspection for policy, orders, portfolio, MCP registry, workflows, integrations, and audit rows. |
+| Django Ninja API | Typed local/staff REST and control endpoints that call service-layer use cases. |
+| MCP | Agent/tool boundary with typed tools, role scopes, policy checks, approval checks, and audit. |
+| CLI | Local operator commands plus generated workspace `./tcx` wrapper behavior. |
+
+The baseline frontend uses Django templates, local static HTMX, and local
+static Alpine. There is no Node, bundler, React, or frontend build step in the
+core package.
+
+---
+
+## Safety Boundary
+
+TradingCodex blocks or constrains:
+
+- direct live broker requests
+- raw broker API calls and raw external MCP execution proxies
+- self-issued approvals
+- restricted-symbol orders
+- expired or payload-mismatched approval receipts
+- duplicate approved-order submissions
+- raw secrets in workspace files, prompts, API responses, MCP responses, audit
+  payloads, generated docs, or shell output
+- unsupported live execution for crypto, macro, options, credit, FX, rates,
+  commodities, or other instruments
+
+TradingCodex is research, workflow, and execution-guardrail tooling. It is not
+financial, investment, legal, tax, or regulatory advice, and it does not
+provide investment recommendations or guarantee returns.
+
+---
+
+## Roadmap
+
+| Status | Milestone |
+| --- | --- |
+| Shipped | Generated Codex workspace, fixed role roster, project MCP config, Django service plane, local web dashboard, Admin, Ninja API, file-native research memory, component registry, policy/audit primitives. |
+| Current `0.2.x` | Central-DB `OrderTicket` rewrite, Broker Center foundations, External MCP Gate, role-scoped MCP tools, paper/stub execution lifecycle, and Python `>=3.11,<3.15` support. |
+| Next | Deeper validation scenarios, richer connector capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
+| Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and live broker support only after explicit product, policy, adapter, and validation work. |
+
+---
+
+## Documentation
+
+| Document | Start here for |
+| --- | --- |
+| [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
+| [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
+| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
+| [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
+| [Harness model](docs/harness.md) | Top-level harness model, components, guardrails, improvement, and naming rules. |
+| [Roles, skills, and workflows](docs/roles-skills-and-workflows.md) | Fixed role roster, no-overlap handoffs, dispatch gates, skills, and strategy behavior. |
+| [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, idempotency, broker safety, secret wall, and required blocks. |
+| [System architecture](docs/system-architecture.md) | Runtime planes, Django app boundaries, central DB ownership, models, and service use cases. |
+| [Interfaces and surfaces](docs/interfaces-and-surfaces.md) | Product web, Admin, API, MCP, CLI, and generated wrapper behavior. |
+| [Validation plan](docs/validation-and-test-plan.md) | Required tests, generated workspace smokes, MCP smokes, and routing scenarios. |
+
+---
+
+## Contributing
+
+Contributions use Apache-2.0 with DCO sign-off. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+For source changes, start with the focused validation command for the touched
+surface, then broaden as needed:
+
+```bash
+python -m pytest
+python manage.py check
+python -m compileall tradingcodex_cli tradingcodex_service apps tests
+```
+
+Harness, agent, workflow, MCP, policy, skill, hook, or template changes also
+need generated-workspace validation. See
+[docs/validation-and-test-plan.md](docs/validation-and-test-plan.md).
+
+---
+
+## License
+
+TradingCodex is an Apache-2.0 open-core project.
+
+Source code, generated workspace templates, and project documentation are
+licensed under the Apache License, Version 2.0 unless marked otherwise. The
+TradingCodex name, future logos, and official product marks are not granted by
+the code license. See [LICENSE](LICENSE), [NOTICE](NOTICE), and
+[TRADEMARKS.md](TRADEMARKS.md).
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=monarchjuno%2Ftradingcodex&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
+ </picture>
+</a>

tradingcodex-0.2.2/README.md

@@ -0,0 +1,282 @@
+> [!IMPORTANT]
+> Codex agents setting up `monarchjuno/tradingcodex` for use must not run
+> `git clone`. In the empty target workspace, run the packaged CLI:
+> `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`.
+> Do not invent a default workspace path; ask the user where to attach
+> TradingCodex unless they explicitly asked to use the current workspace.
+> Clone this repository only when the user explicitly asks to develop,
+> inspect, or modify TradingCodex source code.
+
+# TradingCodex
+
+<div align="center">
+  <a href="https://github.com/monarchjuno/tradingcodex/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/monarchjuno/tradingcodex/ci.yml?branch=main&label=CI"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="Release" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=release"></a>
+  <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
+  <img alt="Django" src="https://img.shields.io/badge/Django-5.2-092E20?logo=django&logoColor=white">
+</div>
+
+<div align="center">
+  <a href="https://github.com/monarchjuno/tradingcodex/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/monarchjuno/tradingcodex?style=social"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/network/members"><img alt="GitHub Forks" src="https://img.shields.io/github/forks/monarchjuno/tradingcodex?style=social"></a>
+  <a href="https://github.com/monarchjuno/tradingcodex/issues"><img alt="GitHub Issues" src="https://img.shields.io/github/issues/monarchjuno/tradingcodex"></a>
+</div>
+
+### Codex-native investment work needs a harness, not a chat transcript.
+
+TradingCodex is a local-first Python/Django trading harness for rigorous
+Codex-assisted research, portfolio review, order-ticket checks, approvals, and
+experimental paper/stub execution. Codex coordinates the work, Django owns the
+durable service plane, and TradingCodex MCP is the executable boundary.
+
+[Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+
+<p align="center">
+  <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
+</p>
+
+---
+
+## About
+
+TradingCodex gives Codex a durable operating system for investment workflows:
+fixed specialist roles, file-native research memory, source-aware handoffs,
+policy and approval services, a central local ledger, and a local web dashboard
+for review.
+
+It is not an autonomous trading bot. Natural-language answers do not become
+broker actions. Live broker adapters are not shipped in the initial core.
+
+---
+
+## Features
+
+| Feature | Description |
+| --- | --- |
+| Codex-native harness | Generates a Codex workspace with `head-manager`, nine fixed subagents, role prompts, skills, hooks, project MCP config, and a local `./tcx` wrapper. |
+| Django service plane | Web, Admin, API, CLI, MCP, and generated hooks call shared application services for policy, orders, approvals, portfolio, audit, integrations, and research indexing. |
+| File-native research memory | Research markdown, role reports, source snapshots, versions, readiness labels, and handoff metadata stay readable in workspace files. |
+| Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
+| MCP execution boundary | Tools are typed, role-scoped, policy-checked, approval-aware, idempotent, adapter-gated, and audited. |
+| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, External MCP Gate metadata, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
+| Broker Center foundations | Register connector profiles, inspect capability profiles, run read-only paper sync, review instrument constraints, and reconcile portfolio state. |
+| OrderTicket lifecycle | Draft, check, approve, submit, cancel, refresh, and inspect order tickets through central DB records and service-layer state transitions. |
+| External MCP Gate | Import external MCP discovery metadata, classify tool risk, scope role access, and block unsafe raw execution or secret proxy paths by default. |
+| Improvement loop | Quality gates, postmortems, optional skills, strategy skills, strict artifact checks, and generated workspace smoke tests turn process gaps into durable improvements. |
+
+---
+
+## Installation
+
+### Option 1 - Attach TradingCodex To The Current Workspace
+
+Run this from the empty workspace where you want Codex agents to work:
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+Then fully quit and restart Codex, open the generated workspace, and start a
+new thread so project MCP config, prompts, skills, and hooks are loaded.
+
+When TradingCodex MCP autostarts the local service, open:
+
+```text
+http://127.0.0.1:48267/
+```
+
+### Option 2 - Install The CLI For Repeated Use
+
+```bash
+uv tool install tradingcodex
+uv tool update-shell
+cd /path/to/target-workspace
+tcx attach .
+./tcx doctor
+```
+
+### Option 3 - Install From GitHub Main
+
+Use this when you need the current GitHub `main` source rather than the latest
+PyPI package:
+
+```bash
+uvx --refresh --from "tradingcodex @ git+https://github.com/monarchjuno/tradingcodex.git@main" tcx attach . && ./tcx doctor
+```
+
+### Option 4 - Develop TradingCodex Source
+
+Clone this repository only for source development, inspection, or modification:
+
+```bash
+git clone https://github.com/monarchjuno/tradingcodex.git
+cd tradingcodex
+python -m pytest
+python manage.py check
+```
+
+See [installation.md](installation.md) for update flows, installer-script
+equivalents, MCP/service details, and smoke checks.
+
+---
+
+## What Sets TradingCodex Apart
+
+TradingCodex competes on workflow discipline, local durability, and execution
+boundaries rather than on black-box automation.
+
+- Local-first: PyPI installs the CLI, Django service plane, generated workspace
+  templates, Admin/Web templates, static assets, and MCP gateway code.
+- Codex-readable by default: research artifacts, skill bundles, role prompts,
+  policy exports, and generated indexes remain ordinary workspace files.
+- Service-layer canonical: Web, Admin, API, CLI, MCP, and hooks do not fork
+  policy, order, approval, execution, portfolio, research, or audit behavior.
+- Strong role model: one `head-manager` coordinates nine fixed specialist
+  subagents and consumes accepted artifacts instead of silently redoing roles.
+- Deterministic executable boundary: every executable path follows
+  `principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit`.
+- Safety-first broker posture: live broker execution is excluded; paper, stub,
+  and reviewed test/sandbox validation remain experimental local harness flows.
+
+---
+
+## Workflow
+
+TradingCodex is designed around handoffs:
+
+```text
+evidence -> analysis -> valuation -> portfolio fit -> risk review
+  -> draft order -> approval receipt -> MCP submit_approved_order
+  -> adapter -> audit/postmortem
+```
+
+The `head-manager` maps the request, dispatches the selected role team, waits
+for accepted artifacts, preserves conflicts, and synthesizes only what the
+workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
+`revise`, `blocked`, or `waiting` instead of being patched over by another role.
+
+---
+
+## Role Roster
+
+| Layer | Agent | Owns |
+| --- | --- | --- |
+| Main agent | `head-manager` | Intake, workflow dispatch, coordination, artifact acceptance, synthesis, and validation/audit status. |
+| Research | `fundamental-analyst` | Business quality, financial statements, filings, economics, and fundamental risks. |
+| Research | `technical-analyst` | Price action, trends, momentum, volume, volatility, and liquidity setup. |
+| Research | `news-analyst` | Verified news, disclosures, event chronology, catalysts, and narrative change. |
+| Market context | `macro-analyst` | Macro, rates, FX, commodities, liquidity, policy, and cross-asset transmission. |
+| Market context | `instrument-analyst` | ETF/index, options, crypto public market structure, credit-signal boundary, and instrument mechanics. |
+| Decision review | `valuation-analyst` | Valuation ranges, scenario assumptions, multiples, sensitivity, and decision-quality gaps. |
+| Portfolio | `portfolio-manager` | Portfolio fit, sizing, concentration, liquidity, opportunity cost, and draft order-ticket readiness. |
+| Risk | `risk-manager` | Downside, restricted-list checks, policy readiness, approval readiness, and approval receipts. |
+| Execution | `execution-operator` | Approved paper/stub execution through TradingCodex MCP only. |
+
+---
+
+## Surfaces
+
+| Surface | Role |
+| --- | --- |
+| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, External MCP Gate, order tickets, portfolio state, and activity. |
+| Django Admin | Local/staff DB inspection for policy, orders, portfolio, MCP registry, workflows, integrations, and audit rows. |
+| Django Ninja API | Typed local/staff REST and control endpoints that call service-layer use cases. |
+| MCP | Agent/tool boundary with typed tools, role scopes, policy checks, approval checks, and audit. |
+| CLI | Local operator commands plus generated workspace `./tcx` wrapper behavior. |
+
+The baseline frontend uses Django templates, local static HTMX, and local
+static Alpine. There is no Node, bundler, React, or frontend build step in the
+core package.
+
+---
+
+## Safety Boundary
+
+TradingCodex blocks or constrains:
+
+- direct live broker requests
+- raw broker API calls and raw external MCP execution proxies
+- self-issued approvals
+- restricted-symbol orders
+- expired or payload-mismatched approval receipts
+- duplicate approved-order submissions
+- raw secrets in workspace files, prompts, API responses, MCP responses, audit
+  payloads, generated docs, or shell output
+- unsupported live execution for crypto, macro, options, credit, FX, rates,
+  commodities, or other instruments
+
+TradingCodex is research, workflow, and execution-guardrail tooling. It is not
+financial, investment, legal, tax, or regulatory advice, and it does not
+provide investment recommendations or guarantee returns.
+
+---
+
+## Roadmap
+
+| Status | Milestone |
+| --- | --- |
+| Shipped | Generated Codex workspace, fixed role roster, project MCP config, Django service plane, local web dashboard, Admin, Ninja API, file-native research memory, component registry, policy/audit primitives. |
+| Current `0.2.x` | Central-DB `OrderTicket` rewrite, Broker Center foundations, External MCP Gate, role-scoped MCP tools, paper/stub execution lifecycle, and Python `>=3.11,<3.15` support. |
+| Next | Deeper validation scenarios, richer connector capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
+| Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and live broker support only after explicit product, policy, adapter, and validation work. |
+
+---
+
+## Documentation
+
+| Document | Start here for |
+| --- | --- |
+| [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
+| [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
+| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
+| [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
+| [Harness model](docs/harness.md) | Top-level harness model, components, guardrails, improvement, and naming rules. |
+| [Roles, skills, and workflows](docs/roles-skills-and-workflows.md) | Fixed role roster, no-overlap handoffs, dispatch gates, skills, and strategy behavior. |
+| [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, idempotency, broker safety, secret wall, and required blocks. |
+| [System architecture](docs/system-architecture.md) | Runtime planes, Django app boundaries, central DB ownership, models, and service use cases. |
+| [Interfaces and surfaces](docs/interfaces-and-surfaces.md) | Product web, Admin, API, MCP, CLI, and generated wrapper behavior. |
+| [Validation plan](docs/validation-and-test-plan.md) | Required tests, generated workspace smokes, MCP smokes, and routing scenarios. |
+
+---
+
+## Contributing
+
+Contributions use Apache-2.0 with DCO sign-off. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+For source changes, start with the focused validation command for the touched
+surface, then broaden as needed:
+
+```bash
+python -m pytest
+python manage.py check
+python -m compileall tradingcodex_cli tradingcodex_service apps tests
+```
+
+Harness, agent, workflow, MCP, policy, skill, hook, or template changes also
+need generated-workspace validation. See
+[docs/validation-and-test-plan.md](docs/validation-and-test-plan.md).
+
+---
+
+## License
+
+TradingCodex is an Apache-2.0 open-core project.
+
+Source code, generated workspace templates, and project documentation are
+licensed under the Apache License, Version 2.0 unless marked otherwise. The
+TradingCodex name, future logos, and official product marks are not granted by
+the code license. See [LICENSE](LICENSE), [NOTICE](NOTICE), and
+[TRADEMARKS.md](TRADEMARKS.md).
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=monarchjuno%2Ftradingcodex&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=monarchjuno/tradingcodex&type=date&legend=top-left" />
+ </picture>
+</a>

{tradingcodex-0.2.1 → tradingcodex-0.2.2}/apps/policy/services.py

@@ -31,13 +31,18 @@ def sync_builtin_principals_and_capabilities(tool_specs: Iterable[Any] | None =
         from tradingcodex_service.mcp_runtime import TOOL_SPECS
 
         tool_specs = TOOL_SPECS
+    tool_specs = tuple(tool_specs)
 
     for role in sorted(BUILTIN_ROLE_IDS):
         Principal.objects.get_or_create(principal_id=role, defaults={"role": role, "active": True})
 
+    expected_builtin_allows: set[tuple[str, str]] = set()
+    builtin_actions: set[str] = set()
     for tool in tool_specs:
         action = tool_capability_action(tool.name, tool.capability_required)
+        builtin_actions.add(action)
         for role in tool.allowed_roles:
+            expected_builtin_allows.add((role, action))
             principal, _ = Principal.objects.get_or_create(principal_id=role, defaults={"role": role, "active": True})
             if principal.role != role:
                 principal.role = role
@@ -49,6 +54,15 @@ def sync_builtin_principals_and_capabilities(tool_specs: Iterable[Any] | None =
                 defaults={"effect": "allow"},
             )
 
+    stale_builtin_allows = Capability.objects.filter(
+        principal__principal_id__in=BUILTIN_ROLE_IDS,
+        action__in=builtin_actions,
+        effect="allow",
+    )
+    for capability in stale_builtin_allows.select_related("principal"):
+        if (capability.principal.principal_id, capability.action) not in expected_builtin_allows:
+            capability.delete()
+
 
 def role_for_principal_id(principal_id: str) -> str:
     principal = Principal.objects.filter(principal_id=principal_id).first()

{tradingcodex-0.2.1 → tradingcodex-0.2.2}/docs/deployment.md

@@ -140,7 +140,7 @@ python3.11 -m venv /tmp/tcx-testpypi
 /tmp/tcx-testpypi/bin/pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  tradingcodex==0.2.1
+  tradingcodex==0.2.2
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -169,7 +169,7 @@ After the PyPI workflow completes:
 
 ```bash
 python3.11 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.1
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.2
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -222,7 +222,8 @@ Use PEP 440 versions:
 - `0.2.0` for the OrderTicket rewrite contract after install, docs, DB
   migration, generated workspace smoke checks, and release e2e checks are stable
 - `0.2.1` for Python `>=3.11,<3.15` support and clone-free setup guidance
-- later patch releases for compatible fixes after `0.2.1`
+- `0.2.2` for dashboard startup behavior fixes after `0.2.1`
+- later patch releases for compatible fixes after `0.2.2`
 - pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
   the next minor contract