tradingcodex 0.2.9__tar.gz → 0.3.0__tar.gz

{tradingcodex-0.2.9 → tradingcodex-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.2.9
-Summary: Codex-native trading harness with a Django service plane and approved action boundary.
+Version: 0.3.0
+Summary: Agentic investment workflow harness for Codex-native research and service-gated execution checks.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
 Keywords: trading,django,codex,mcp,portfolio,research
@@ -55,14 +55,14 @@ Dynamic: license-file
   <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.
+### Codex-native investment work needs an agentic 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
-service-gated execution checks. Codex coordinates the work, Django owns the
-durable service plane, and TradingCodex owns the executable boundary.
+TradingCodex is an agentic investment workflow harness for Codex-native
+research, thesis review, portfolio/risk handoffs, and service-gated execution
+checks. Codex coordinates the work, specialist agents own bounded judgments,
+and TradingCodex keeps execution behind explicit service gates.
 
-[Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+[Start Skills](#start-with-these-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
@@ -72,10 +72,10 @@ durable service plane, and TradingCodex owns the executable boundary.
 
 ## 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.
+TradingCodex gives Codex a durable operating system for agentic investment
+workflows: fixed specialist roles, independent judgment review, source-aware
+handoffs, thesis lifecycle memory, policy and approval services, and a local
+review dashboard.
 
 It is not an autonomous trading bot. Natural-language answers do not become
 broker actions. The core ships paper execution by default; live broker support
@@ -83,28 +83,26 @@ comes only from installed, reviewed providers and explicit live gates.
 
 ---
 
-## Features
+## Start With These Skills
 
-| 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. |
-| Decision Workflow Alpha | Turn a natural-language investment idea into a Codex-native workflow plan and Decision Package under `trading/decisions/`. |
-| Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
-| Approved action boundary | Actions are typed, role-scoped, policy-checked, approval-aware, duplicate-request checked, connection-gated, and audited. |
-| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, Data Sources, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
-| Broker Center foundations | Connect provider-driven broker profiles, list installed providers, scaffold/register advanced connectors, inspect capability profiles, run account 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. |
-| Data Sources gate | Import external source discovery metadata, review available actions, scope role access, and block unsafe raw execution or secret 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. |
+TradingCodex is easiest to use by choosing the right user-facing entry skill:
+
+| Start skill | Use when | Stops before |
+| --- | --- | --- |
+| `tcx-workflow` | Investment research, thesis review, Decision Packages, portfolio fit, risk review, or order-readiness workflow planning. | Substantive synthesis before accepted role artifacts; approval or execution without service gates. |
+| `strategy-creator` | Turning user rules into reusable strategy skills, updating strategy criteria, activating, archiving, or inspecting strategy state. | Live ticker analysis, recommendation, order approval, execution, or policy changes. |
+| `tcx-server` | Checking dashboard/service health, doctor output, update status, MCP readiness, DB path, or startup recovery. | Investment judgment, broker execution, raw secrets, or template edits. |
+| `tcx-build` | Build-mode connector/provider work, broker/API scaffolding, capability profile wiring, credential-ref setup, and validation. | Raw secret handling, live order submission, or investment subagent dispatch. |
+
+Most investment prompts enter through natural language, then the hook writes
+compact intake and `head-manager` uses `tcx-workflow` to draft, validate, and
+record the staged plan before dispatch. See
+[User-facing skills](docs/user-facing-skills.md) for the detailed routing map.
 
 ---
 
 ## Installation
 
-### Option 1 - Attach TradingCodex To The Current Workspace
-
 Run this from the empty workspace where you want Codex agents to work:
 
 ```bash
@@ -120,64 +118,9 @@ When TradingCodex MCP autostarts the local service, open:
 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
-  a fixed requester, permission, policy, payload, approval, duplicate-request,
-  connection, and audit sequence.
-- Safety-first broker posture: paper is built in; live broker execution requires
-  an installed provider plus workspace config, policy, environment opt-in,
-  approval, confirmation, idempotency, sync, and audit gates.
-- Broker control plane: TradingCodex stores connector state, capability
-  profiles, mapping review, approval, execution, reconciliation, and audit;
-  provider adapters absorb broker-specific REST, SDK, MCP, or manual interface
-  differences behind canonical service/MCP tools.
+See [installation.md](installation.md) for persistent CLI install, GitHub-main
+install, source-development setup, update flows, installer-script equivalents,
+MCP/service details, and smoke checks.
 
 ---
 
@@ -209,25 +152,48 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 | 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. |
+| Decision review | `judgment-reviewer` | Independent challenge review of accepted artifacts for contrary evidence, source trust, overconfidence, update triggers, and invalidation conditions. |
 | 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 submission/cancel/status through the TradingCodex service boundary only; live requires all gates. |
 
 ---
 
-## Surfaces
+## Key Features
 
-| Surface | Role |
+| Feature | What it gives you |
 | --- | --- |
-| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, Data Sources, 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. |
+| Agentic workflow planning | Natural-language prompts become staged plans, selected role teams, accepted artifacts, and explicit `waiting`, `revise`, or `blocked` states. |
+| Independent judgment review | `judgment-reviewer` challenges accepted artifacts for contrary evidence, source trust, overconfidence, update triggers, and invalidation conditions. |
+| Decision Packages | Investment theses keep forecastable claims, lifecycle assumptions, contrary evidence, owner roles, follow-up, and postmortem requirements. |
+| Strategy skills | `strategy-creator` turns user rules into reusable strategy skills without granting order approval, execution, broker, or policy authority. |
+| File-native research memory | Research markdown, role reports, source snapshots, readiness labels, versions, and handoff metadata remain ordinary workspace files. |
+| Service-gated execution | Order tickets, approvals, policy checks, idempotency, broker connections, account sync, and audit stay behind Django service-layer gates. |
+| Local review surfaces | Web, Admin, API, MCP, CLI, and generated hooks share the same service plane for review, status, research, Broker Center, orders, and portfolio state. |
 
-The baseline frontend uses Django templates, local static HTMX, and small plain
-JavaScript. There is no Node, bundler, React, or frontend build step in the core
-package.
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+  U["User prompt"] --> H["Codex head-manager"]
+  H --> R["Fixed role agents"]
+  R --> A["Accepted artifacts"]
+  A --> J["judgment-reviewer"]
+  J --> D["Decision Package"]
+  D --> S["Django service plane"]
+  S --> G["Policy / approval / audit gates"]
+  G --> E["Paper execution or gated live provider"]
+  S --> W["Web / Admin / API / MCP / CLI"]
+  S --> M["File-native research memory"]
+```
+
+The architecture is intentionally small: Codex owns coordination and role
+handoffs; Django owns durable policy, order, approval, portfolio, integration,
+research, and audit behavior. The core package uses Django templates, local
+static HTMX, and small plain JavaScript. There is no Node, bundler, React, or
+frontend build step.
 
 ---
 
@@ -257,20 +223,25 @@ provide investment recommendations or guarantee returns.
 | 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, provider-driven Broker Center foundations, Data Sources gate, role-scoped actions, live-gated execution lifecycle, and Python `>=3.11,<3.15` support. |
-| Next | Codex-native Decision Packages, deeper validation scenarios, richer provider capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
+| Current `0.3.0` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop, provider capability profiles, and Python `>=3.11,<3.15` support. |
+| Next | Deeper validation scenarios, richer provider 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 broker-specific live providers only after explicit product, policy, adapter, and validation work. |
 
 ---
 
 ## Documentation
 
-| Document | Start here for |
+`README.md` is the product overview. The `docs/` directory is the human-readable
+source of truth for detailed product behavior, safety, architecture, workflow,
+validation, and release policy.
+
+| Start here | Use 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. |
+| [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
+| [User-facing skills](docs/user-facing-skills.md) | Which skill starts which user workflow and what each entrypoint must not do. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
+| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Workspace orchestration model](docs/harness.md) | Top-level workflow 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. |

{tradingcodex-0.2.9 → tradingcodex-0.3.0}/README.md

@@ -24,14 +24,14 @@
   <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.
+### Codex-native investment work needs an agentic 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
-service-gated execution checks. Codex coordinates the work, Django owns the
-durable service plane, and TradingCodex owns the executable boundary.
+TradingCodex is an agentic investment workflow harness for Codex-native
+research, thesis review, portfolio/risk handoffs, and service-gated execution
+checks. Codex coordinates the work, specialist agents own bounded judgments,
+and TradingCodex keeps execution behind explicit service gates.
 
-[Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+[Start Skills](#start-with-these-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
@@ -41,10 +41,10 @@ durable service plane, and TradingCodex owns the executable boundary.
 
 ## 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.
+TradingCodex gives Codex a durable operating system for agentic investment
+workflows: fixed specialist roles, independent judgment review, source-aware
+handoffs, thesis lifecycle memory, policy and approval services, and a local
+review dashboard.
 
 It is not an autonomous trading bot. Natural-language answers do not become
 broker actions. The core ships paper execution by default; live broker support
@@ -52,28 +52,26 @@ comes only from installed, reviewed providers and explicit live gates.
 
 ---
 
-## Features
+## Start With These Skills
 
-| 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. |
-| Decision Workflow Alpha | Turn a natural-language investment idea into a Codex-native workflow plan and Decision Package under `trading/decisions/`. |
-| Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
-| Approved action boundary | Actions are typed, role-scoped, policy-checked, approval-aware, duplicate-request checked, connection-gated, and audited. |
-| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, Data Sources, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
-| Broker Center foundations | Connect provider-driven broker profiles, list installed providers, scaffold/register advanced connectors, inspect capability profiles, run account 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. |
-| Data Sources gate | Import external source discovery metadata, review available actions, scope role access, and block unsafe raw execution or secret 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. |
+TradingCodex is easiest to use by choosing the right user-facing entry skill:
+
+| Start skill | Use when | Stops before |
+| --- | --- | --- |
+| `tcx-workflow` | Investment research, thesis review, Decision Packages, portfolio fit, risk review, or order-readiness workflow planning. | Substantive synthesis before accepted role artifacts; approval or execution without service gates. |
+| `strategy-creator` | Turning user rules into reusable strategy skills, updating strategy criteria, activating, archiving, or inspecting strategy state. | Live ticker analysis, recommendation, order approval, execution, or policy changes. |
+| `tcx-server` | Checking dashboard/service health, doctor output, update status, MCP readiness, DB path, or startup recovery. | Investment judgment, broker execution, raw secrets, or template edits. |
+| `tcx-build` | Build-mode connector/provider work, broker/API scaffolding, capability profile wiring, credential-ref setup, and validation. | Raw secret handling, live order submission, or investment subagent dispatch. |
+
+Most investment prompts enter through natural language, then the hook writes
+compact intake and `head-manager` uses `tcx-workflow` to draft, validate, and
+record the staged plan before dispatch. See
+[User-facing skills](docs/user-facing-skills.md) for the detailed routing map.
 
 ---
 
 ## Installation
 
-### Option 1 - Attach TradingCodex To The Current Workspace
-
 Run this from the empty workspace where you want Codex agents to work:
 
 ```bash
@@ -89,64 +87,9 @@ When TradingCodex MCP autostarts the local service, open:
 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
-  a fixed requester, permission, policy, payload, approval, duplicate-request,
-  connection, and audit sequence.
-- Safety-first broker posture: paper is built in; live broker execution requires
-  an installed provider plus workspace config, policy, environment opt-in,
-  approval, confirmation, idempotency, sync, and audit gates.
-- Broker control plane: TradingCodex stores connector state, capability
-  profiles, mapping review, approval, execution, reconciliation, and audit;
-  provider adapters absorb broker-specific REST, SDK, MCP, or manual interface
-  differences behind canonical service/MCP tools.
+See [installation.md](installation.md) for persistent CLI install, GitHub-main
+install, source-development setup, update flows, installer-script equivalents,
+MCP/service details, and smoke checks.
 
 ---
 
@@ -178,25 +121,48 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 | 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. |
+| Decision review | `judgment-reviewer` | Independent challenge review of accepted artifacts for contrary evidence, source trust, overconfidence, update triggers, and invalidation conditions. |
 | 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 submission/cancel/status through the TradingCodex service boundary only; live requires all gates. |
 
 ---
 
-## Surfaces
+## Key Features
 
-| Surface | Role |
+| Feature | What it gives you |
 | --- | --- |
-| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, Data Sources, 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. |
+| Agentic workflow planning | Natural-language prompts become staged plans, selected role teams, accepted artifacts, and explicit `waiting`, `revise`, or `blocked` states. |
+| Independent judgment review | `judgment-reviewer` challenges accepted artifacts for contrary evidence, source trust, overconfidence, update triggers, and invalidation conditions. |
+| Decision Packages | Investment theses keep forecastable claims, lifecycle assumptions, contrary evidence, owner roles, follow-up, and postmortem requirements. |
+| Strategy skills | `strategy-creator` turns user rules into reusable strategy skills without granting order approval, execution, broker, or policy authority. |
+| File-native research memory | Research markdown, role reports, source snapshots, readiness labels, versions, and handoff metadata remain ordinary workspace files. |
+| Service-gated execution | Order tickets, approvals, policy checks, idempotency, broker connections, account sync, and audit stay behind Django service-layer gates. |
+| Local review surfaces | Web, Admin, API, MCP, CLI, and generated hooks share the same service plane for review, status, research, Broker Center, orders, and portfolio state. |
 
-The baseline frontend uses Django templates, local static HTMX, and small plain
-JavaScript. There is no Node, bundler, React, or frontend build step in the core
-package.
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+  U["User prompt"] --> H["Codex head-manager"]
+  H --> R["Fixed role agents"]
+  R --> A["Accepted artifacts"]
+  A --> J["judgment-reviewer"]
+  J --> D["Decision Package"]
+  D --> S["Django service plane"]
+  S --> G["Policy / approval / audit gates"]
+  G --> E["Paper execution or gated live provider"]
+  S --> W["Web / Admin / API / MCP / CLI"]
+  S --> M["File-native research memory"]
+```
+
+The architecture is intentionally small: Codex owns coordination and role
+handoffs; Django owns durable policy, order, approval, portfolio, integration,
+research, and audit behavior. The core package uses Django templates, local
+static HTMX, and small plain JavaScript. There is no Node, bundler, React, or
+frontend build step.
 
 ---
 
@@ -226,20 +192,25 @@ provide investment recommendations or guarantee returns.
 | 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, provider-driven Broker Center foundations, Data Sources gate, role-scoped actions, live-gated execution lifecycle, and Python `>=3.11,<3.15` support. |
-| Next | Codex-native Decision Packages, deeper validation scenarios, richer provider capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
+| Current `0.3.0` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop, provider capability profiles, and Python `>=3.11,<3.15` support. |
+| Next | Deeper validation scenarios, richer provider 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 broker-specific live providers only after explicit product, policy, adapter, and validation work. |
 
 ---
 
 ## Documentation
 
-| Document | Start here for |
+`README.md` is the product overview. The `docs/` directory is the human-readable
+source of truth for detailed product behavior, safety, architecture, workflow,
+validation, and release policy.
+
+| Start here | Use 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. |
+| [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
+| [User-facing skills](docs/user-facing-skills.md) | Which skill starts which user workflow and what each entrypoint must not do. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
+| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Workspace orchestration model](docs/harness.md) | Top-level workflow 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. |

tradingcodex-0.3.0/docs/README.md

@@ -0,0 +1,97 @@
+# TradingCodex Documentation
+
+This directory is the human-readable source of truth linked from the public `README.md`. It explains the product model, operating rules, safety boundaries, generated workspace behavior, implementation architecture, validation expectations, release policy, and licensing posture.
+
+Use these docs when you want the deeper "why" behind TradingCodex behavior. Coding agents should use `openwiki/` for fast source navigation, then return here before changing durable product behavior.
+
+## How To Read These Docs
+
+| Reader goal | Start with | Then read |
+| --- | --- | --- |
+| Understand TradingCodex quickly | [core-concepts-and-rules.md](./core-concepts-and-rules.md) | [product-direction.md](./product-direction.md), [harness.md](./harness.md) |
+| Install or update a workspace | [../installation.md](../installation.md) | [generated-workspaces.md](./generated-workspaces.md), [deployment.md](./deployment.md) |
+| Understand which user skill to start with | [user-facing-skills.md](./user-facing-skills.md) | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md), [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) |
+| Understand the investment workflow | [harness.md](./harness.md) | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md), [research-memory-and-artifacts.md](./research-memory-and-artifacts.md) |
+| Understand safety and execution boundaries | [safety-policy-and-execution.md](./safety-policy-and-execution.md) | [guardrails.md](./guardrails.md), [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) |
+| Understand implementation architecture | [system-architecture.md](./system-architecture.md) | [interfaces-and-surfaces.md](./interfaces-and-surfaces.md), [components.md](./components.md) |
+| Change prompts, skills, hooks, routing, or generated workspaces | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md) | [generated-workspaces.md](./generated-workspaces.md), [validation-and-test-plan.md](./validation-and-test-plan.md) |
+| Validate a change before release or handoff | [validation-and-test-plan.md](./validation-and-test-plan.md) | The topic document for the changed area |
+
+## Documentation Layers
+
+| Layer | Audience | Role |
+| --- | --- | --- |
+| `README.md` | New users and evaluators | Product summary, installation path, feature overview, and links into these docs. |
+| `installation.md` | Operators | Setup, update, installer, MCP/service startup, and smoke checks. |
+| `docs/` | Humans and maintainers | Durable product source of truth and deeper design rationale. |
+| `openwiki/` | Coding agents | Fast repository map and edit/validation routing. |
+| `AGENTS.md` | Coding agents | Hard rules, setup guard, coding rules, and validation requirements. |
+
+If these layers disagree, treat `docs/` as the durable product intent and fix the mismatch deliberately. Do not let hidden behavior drift live only in code, tests, prompts, skills, hooks, or generated templates.
+
+## Core Documents
+
+| Document | Owns |
+| --- | --- |
+| [core-concepts-and-rules.md](./core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, role boundaries, execution lifecycle, research memory, and documentation rules. |
+| [product-direction.md](./product-direction.md) | Product thesis, target user posture, goals, non-goals, product language, default runtime, universe scope, and open-core posture. |
+| [harness.md](./harness.md) | Top-level harness model: roles, skills, service-layer state, policy, MCP, research memory, approvals, execution adapters, audit, and improvement loops. |
+| [components.md](./components.md) | Component-first maintenance registry, taxonomy tags, owned surfaces, dependencies, capabilities, and validation. |
+
+## Workflow And Agent Documents
+
+| Document | Owns |
+| --- | --- |
+| [user-facing-skills.md](./user-facing-skills.md) | User-facing entry skills, routing posture, and non-entrypoint skill boundaries. |
+| [roles-skills-and-workflows.md](./roles-skills-and-workflows.md) | Fixed role roster, no-overlap role contract, head-manager dispatch gate, skills, strategy skills, subagent isolation, workflow routing, and module graph. |
+| [research-memory-and-artifacts.md](./research-memory-and-artifacts.md) | File-native research memory, source snapshots, artifact paths, readiness labels, report quality floor, forecast ledger posture, and handoff metadata. |
+| [financial-workflow-references.md](./financial-workflow-references.md) | Research-backed finance workflow principles and non-expert UX requirements for workflow intake and handoffs. |
+| [artifact-supervisor-loop-prd.md](./artifact-supervisor-loop-prd.md) | Artifact Supervisor Loop PRD, bounded follow-up routing, lane escalation, loop state, and Decision Quality Spine preservation. |
+
+## Safety And Improvement Documents
+
+| Document | Owns |
+| --- | --- |
+| [guardrails.md](./guardrails.md) | Guardrail taxonomy: guidance, enforcement, and information barriers. |
+| [safety-policy-and-execution.md](./safety-policy-and-execution.md) | Permission checks, approval rules, execution lifecycle, adapter boundary, external MCP gate, blocked actions, and secret handling. |
+| [improvement-loop.md](./improvement-loop.md) | Workflow quality, research memory, skill evolution, postmortems, validation feedback, and quality-learning loops. |
+
+## Implementation And Operations Documents
+
+| Document | Owns |
+| --- | --- |
+| [system-architecture.md](./system-architecture.md) | Django modular monolith, central DB ownership, app boundaries, runtime planes, service-layer use cases, and core models. |
+| [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) | Product web, Django Admin, Django Ninja API, MCP boundary, CLI, generated wrapper behavior, and external MCP surface. |
+| [generated-workspaces.md](./generated-workspaces.md) | `tcx attach`, `tcx init`, `tcx update`, generated files, project-scoped MCP config, hooks, workspace provenance, profile scope, and template rules. |
+| [validation-and-test-plan.md](./validation-and-test-plan.md) | Required validation commands, unit/API/generator/smoke coverage, MCP smokes, broker provider smokes, routing scenarios, and release-sensitive checks. |
+| [deployment.md](./deployment.md) | PyPI/TestPyPI release process, CI/CD, Trusted Publishing, installer/update policy, versioning, and what is not deployed. |
+| [licensing-and-commercialization.md](./licensing-and-commercialization.md) | Apache-2.0 open-core boundary, generated workspace ownership, contributions, trademark posture, and legal review needs. |
+
+## Change-To-Docs Map
+
+| Change type | Update these docs |
+| --- | --- |
+| Product scope, non-goals, default runtime, product language, or release posture | `product-direction.md`, `core-concepts-and-rules.md` |
+| Top-level harness model, component registry, guardrail/improvement taxonomy, or cross-cutting concept language | `harness.md`, `components.md`, `guardrails.md`, `improvement-loop.md`, `core-concepts-and-rules.md` |
+| User-facing workflow intake, suitability/profile context, plain-English output, or professional finance framing | `financial-workflow-references.md`, `interfaces-and-surfaces.md`, `roles-skills-and-workflows.md` |
+| Role roster, head-manager dispatch, skills, strategy behavior, routing, information barriers, or handoff quality | `roles-skills-and-workflows.md`, `artifact-supervisor-loop-prd.md`, `core-concepts-and-rules.md` |
+| Research memory, source snapshots, forecast ledgers, readiness labels, artifact paths, report quality, or markdown preview | `research-memory-and-artifacts.md`, `improvement-loop.md`, `artifact-supervisor-loop-prd.md` |
+| Policy, permissions, approvals, idempotency, execution, adapters, broker safety, external MCP gate, or secret handling | `safety-policy-and-execution.md`, `guardrails.md`, `core-concepts-and-rules.md` |
+| Django apps, models, service-layer contracts, central DB ownership, or runtime topology | `system-architecture.md` |
+| Product web, Admin, REST, MCP, CLI, or generated wrapper behavior | `interfaces-and-surfaces.md` |
+| Workspace templates, bootstrap, hooks, project MCP config, generated files, or update behavior | `generated-workspaces.md` |
+| Test expectations, smoke flows, validation commands, or regression scenarios | `validation-and-test-plan.md` |
+| Packaging, installer, release automation, versioning, or distribution boundary | `deployment.md`, `installation.md` |
+| License, contribution, trademark, generated workspace ownership, or commercialization boundary | `licensing-and-commercialization.md` |
+
+## Source-Of-Truth Principles
+
+| Principle | Meaning |
+| --- | --- |
+| Docs first for product behavior | Durable rules for safety, roles, workflows, execution, generated workspaces, and release posture belong in these docs. |
+| Update docs with behavior | Code, templates, prompts, hooks, tests, and generated artifacts that change durable behavior should update the owning doc in the same change. |
+| Keep `README.md` concise | The public README should explain the product and route readers here instead of duplicating every rule. |
+| Keep OpenWiki agent-focused | `openwiki/` should help agents work efficiently and link back to these docs for durable explanations. |
+| Keep product language English | TradingCodex product copy, generated workspace guidance, Admin UI, CLI help, role prompts, durable docs, and examples are written in English unless a reviewed localization layer is being built. |
+| Product web is review-first | The `/` web app opens on workflow planning and can preview handoffs; it does not spawn agents, approve orders, or execute orders. |
+| Open-core boundary is explicit | Apache-2.0 covers the repository open core; trademarks and official commercial offerings remain separately governed. |