PyPI - tradingcodex - Versions diffs - 0.2.10__tar.gz → 0.3.1__tar.gz - Mend

tradingcodex 0.2.10tar.gz → 0.3.1tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (314) hide show

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/PKG-INFO RENAMED Viewed

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.2.10
-Summary: Codex-native trading harness with a Django service plane and approved action boundary.
+Version: 0.3.1
+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)
+[User-Facing Skills](#user-facing-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,32 @@ comes only from installed, reviewed providers and explicit live gates.
 ---
-## Features
+## User-Facing 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 skill:
+| Primary 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. |
+| Supporting skill | Use when | Main output |
+| --- | --- | --- |
+| `plan-workflow` | You want an explicit workflow plan before role dispatch or implementation. | Bounded plan with selected stages, roles, gates, and waiting/revise/blocked posture. |
+| `automate-workflow` | You want to define a repeatable workflow automation without executing trades. | Automation recipe, trigger scope, guardrails, and review requirements. |
+| `postmortem` | A workflow, decision, artifact, or execution/process step needs review after the fact. | Failure analysis, missed assumptions, source-quality lessons, and future warning patterns. |
+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 +124,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 +158,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. |
+---
+## Architecture
+```mermaid
+flowchart LR
+  user([User prompt]) --> manager[Head manager]
+  manager --> agents[Fixed role agents]
+  agents --> artifacts[Accepted artifacts]
+  artifacts --> reviewer[Judgment reviewer]
+  reviewer --> decision[Decision Package]
+  decision --> service[Django service plane]
+  service --> gates[Policy approval audit gates]
+  gates --> execution[Paper execution or gated live provider]
+  service --> surfaces[Web Admin API MCP CLI]
+  service --> memory[File native research memory]
+```
-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.
+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,8 +229,8 @@ 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.1` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop closure state, Evidence Run/Validation Cards, 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. |
 ---
@@ -273,6 +245,7 @@ validation, and release policy.
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
 | [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 primary or supporting skill fits each user workflow and what each 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. |

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/README.md RENAMED Viewed

@@ -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)
+[User-Facing Skills](#user-facing-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,32 @@ comes only from installed, reviewed providers and explicit live gates.
 ---
-## Features
+## User-Facing 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 skill:
+| Primary 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. |
+| Supporting skill | Use when | Main output |
+| --- | --- | --- |
+| `plan-workflow` | You want an explicit workflow plan before role dispatch or implementation. | Bounded plan with selected stages, roles, gates, and waiting/revise/blocked posture. |
+| `automate-workflow` | You want to define a repeatable workflow automation without executing trades. | Automation recipe, trigger scope, guardrails, and review requirements. |
+| `postmortem` | A workflow, decision, artifact, or execution/process step needs review after the fact. | Failure analysis, missed assumptions, source-quality lessons, and future warning patterns. |
+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 +93,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 +127,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. |
+---
+## Architecture
+```mermaid
+flowchart LR
+  user([User prompt]) --> manager[Head manager]
+  manager --> agents[Fixed role agents]
+  agents --> artifacts[Accepted artifacts]
+  artifacts --> reviewer[Judgment reviewer]
+  reviewer --> decision[Decision Package]
+  decision --> service[Django service plane]
+  service --> gates[Policy approval audit gates]
+  gates --> execution[Paper execution or gated live provider]
+  service --> surfaces[Web Admin API MCP CLI]
+  service --> memory[File native research memory]
+```
-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.
+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,8 +198,8 @@ 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.1` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop closure state, Evidence Run/Validation Cards, 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. |
 ---
@@ -242,6 +214,7 @@ validation, and release policy.
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
 | [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 primary or supporting skill fits each user workflow and what each 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. |

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/docs/README.md RENAMED Viewed

@@ -10,6 +10,7 @@ Use these docs when you want the deeper "why" behind TradingCodex behavior. Codi
 | --- | --- | --- |
 | 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) |
@@ -41,6 +42,7 @@ If these layers disagree, treat `docs/` as the durable product intent and fix th
 | Document | Owns |
 | --- | --- |
+| [user-facing-skills.md](./user-facing-skills.md) | User-facing primary and supporting skills, routing posture, and role-owned 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. |
@@ -52,7 +54,7 @@ If these layers disagree, treat `docs/` as the durable product intent and fix th
 | --- | --- |
 | [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. |
+| [improvement-loop.md](./improvement-loop.md) | Workflow quality, research memory, improve records, skill evolution, postmortem review, validation feedback, and quality-learning loops. |
 ## Implementation And Operations Documents

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/docs/artifact-supervisor-loop-prd.md RENAMED Viewed

@@ -40,13 +40,17 @@ context discipline, approval gates, execution boundaries, and user scope.
   escalation-only sets.
 - Extend research artifact metadata with explicit follow-up requests, trigger
   types, materiality, suggested consent posture, and loop provenance.
+- Let artifacts preserve `improvements` so repeated investment judgment
+  findings can feed `improve` review and later workflows instead of hidden
+  prompt drift.
 - Store loop state as file-native workspace state for Codex inspection,
   context-budget audit, product web preview, concurrent Codex app threads, and
   postmortems.
 - Keep all follow-up briefs compact: artifact path, context summary,
   trigger, delta question, constraints, and blocked actions.
-- Preserve Decision Quality Spine expectations inside the loop rather than
-  keeping them as a separate monolithic PRD.
+- Preserve Decision Quality Spine expectations, including source trust and
+  agent judgment review, inside the loop rather than keeping them as a separate
+  monolithic PRD.
 - Add tests and smoke checks that prove loops improve quality without widening
   authority.
@@ -337,8 +341,11 @@ Add file-native loop state records:
 ```text
 .tradingcodex/mainagent/workflow-loop-state.json                    # latest compact summary / pointer
+.tradingcodex/mainagent/latest-workflow-intake.json                 # latest compact intake hint
+.tradingcodex/mainagent/latest-workflow-plan.json                   # latest validated staged plan
+.tradingcodex/mainagent/workflows/<workflow_run_id>/intake.json
+.tradingcodex/mainagent/workflows/<workflow_run_id>/workflow-plan.json
 .tradingcodex/mainagent/workflows/<workflow_run_id>/loop-state.json # canonical run state
-.tradingcodex/mainagent/workflows/<workflow_run_id>/prompt-gate.json
 .tradingcodex/mainagent/session-workflow-runs.json                  # Codex session/thread -> workflow_run_id map
 ```
@@ -366,6 +373,7 @@ Canonical run-state shape:
   "completed_artifacts": [],
   "loop_decisions": [],
   "escalation_proposals": [],
+  "improvements": [],
   "blocked_actions": [],
   "stop_reason": ""
 }
@@ -409,6 +417,8 @@ Update these surfaces together:
 - Product web
   - preview loop state, follow-up requests, escalation proposals, and blocked
     actions without spawning agents, approving orders, or executing orders.
+  - show improve records as analysis-memory review items without applying
+    skill, policy, prompt, validation, approval, broker, or execution changes.
   - first release escalation proposals are read-only; escalation approval stays
     Codex-prompt or CLI driven with explicit user wording captured in audit.
@@ -530,7 +540,8 @@ follow-up is needed.
   synthesize using a closed action set.
 - Loop state is visible in workspace files and audit trails.
 - Context stays compact across iterations.
-- Decision Quality Spine fields still apply inside selected lanes.
+- Decision Quality Spine fields, source trust notes, and judgment-review fields
+  still apply inside selected lanes.
 - Approval, execution, broker, secret, and policy boundaries are unchanged.
 - Generated workspace validation catches loop drift, unauthorized expansion,
   malformed follow-up requests, and unsupported synthesis.

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/docs/components.md RENAMED Viewed

@@ -37,10 +37,10 @@ paths clear.
 | --- | --- | --- |
 | `investment-request-routing` | Classifies user intent and activates fixed-role workflows. | `guardrail.guidance`, `improvement.workflow_quality` |
 | `fixed-role-dispatch` | Maintains head-manager, fixed subagent routing, and no-overlap handoff boundaries. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality` |
-| `research-memory` | Stores source-aware research artifacts, versions, snapshots, and exports. | `improvement.research_memory` |
-| `workflow-quality-gates` | Defines lane selection, Artifact Supervisor Loop policy, Decision Quality Spine, handoff acceptance, artifact readiness, claim discipline, and synthesis gates. | `guardrail.guidance`, `improvement.workflow_quality` |
+| `research-memory` | Stores source-aware research artifacts, versions, snapshots, Evidence Run Cards, Validation Cards, and exports. | `improvement.research_memory` |
+| `workflow-quality-gates` | Defines lane selection, Artifact Supervisor Loop policy, Decision Quality Spine, agent judgment review, handoff acceptance, artifact readiness, claim discipline, and synthesis gates. | `guardrail.guidance`, `improvement.workflow_quality` |
 | `decision-package` | Wraps workflow plans, artifact paths, profile gaps, blocked actions, and next steps in Codex-readable workspace markdown. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
-| `artifact-quality-contract` | Evaluates workspace artifacts and forecast ledgers for source/as-of posture, claim tags, handoff state, confidence, missing evidence, and next-recipient routing metadata. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
+| `artifact-quality-contract` | Evaluates workspace artifacts, Evidence Run Cards, Validation Cards, source snapshots, and forecast ledgers for source/as-of posture, source trust, data-boundary warnings, claim tags, handoff state, confidence, missing evidence, judgment-review fields, and next-recipient routing metadata. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
 | `context-efficiency-contract` | Keeps workflows bounded through compact briefs, artifact references, context summaries, source snapshot IDs, targeted full-artifact reads, and `subagents context-audit` validation. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality`, `improvement.context_efficiency` |
 | `responsibility-boundary-contract` | Separates durable role identity, tool permissions, skill procedures, artifact contracts, and projection ownership so changes stay local. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality`, `improvement.skill_evolution` |
 | `external-data-source-gate` | Keeps external evidence read-only and source-aware. | `guardrail.guidance`, `improvement.workflow_quality` |
@@ -52,7 +52,7 @@ paths clear.
 | `execution-boundary` | Keeps execution behind role action allowlists, approval, duplicate-request, connection, and audit checks. | `guardrail.enforcement`, `guardrail.information_barrier` |
 | `audit-ledger` | Records policy, MCP, order, approval, execution, and hook events. | `guardrail.enforcement`, `improvement.validation_feedback` |
 | `skill-improvement-loop` | Keeps core skills, strategy skills, and role-local optional skill files visible through validation, generated manifests, and read-only status. | `improvement.skill_evolution`, `guardrail.guidance` |
-| `postmortem-loop` | Turns rejected orders, process failures, thesis changes, artifact-loop blocks/escalations, and executions into improvements. | `improvement.postmortems`, `improvement.validation_feedback` |
+| `postmortem-loop` | Turns rejected orders, process failures, thesis changes, artifact-loop blocks/escalations, and executions into improve records for later judgment review. | `improvement.postmortems`, `improvement.validation_feedback` |
 | `paper-execution` | Provides experimental local paper and validation-only execution paths behind the approved action boundary. | `guardrail.enforcement` |
 ## Runtime Surfaces

{tradingcodex-0.2.10 → tradingcodex-0.3.1}/docs/core-concepts-and-rules.md RENAMED Viewed

@@ -81,7 +81,7 @@ portfolio state or execution policy.
 ## Role Boundary Snapshot
-TradingCodex always uses `head-manager` as the main coordinator with nine fixed
+TradingCodex always uses `head-manager` as the main coordinator with ten fixed
 subagents. Detailed responsibilities live in
 [roles-skills-and-workflows.md](./roles-skills-and-workflows.md).

tradingcodex 0.2.10__tar.gz → 0.3.1__tar.gz

tradingcodex 0.2.10tar.gz → 0.3.1tar.gz