tradingcodex 0.2.10__tar.gz → 0.3.0__tar.gz

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

@@ -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.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. |
+
+---
+
+## 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 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 +223,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.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. |
 
 ---
@@ -273,6 +239,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 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. |

{tradingcodex-0.2.10 → 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. |
+
+---
+
+## 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 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 +192,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.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. |
 
 ---
@@ -242,6 +208,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 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. |

{tradingcodex-0.2.10 → tradingcodex-0.3.0}/docs/README.md

@@ -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 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. |

{tradingcodex-0.2.10 → tradingcodex-0.3.0}/docs/artifact-supervisor-loop-prd.md

@@ -45,8 +45,9 @@ context discipline, approval gates, execution boundaries, and user scope.
   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 +338,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
 ```
 
@@ -530,7 +534,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.0}/docs/components.md

@@ -38,9 +38,9 @@ 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` |
+| `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 and forecast ledgers for source/as-of posture, source trust, 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` |

{tradingcodex-0.2.10 → tradingcodex-0.3.0}/docs/core-concepts-and-rules.md

@@ -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 → tradingcodex-0.3.0}/docs/deployment.md

@@ -3,7 +3,8 @@
 TradingCodex is distributed as a Python package on PyPI. The package name is
 `tradingcodex`; the installed command is `tcx`.
 
-TradingCodex is local-first software. A PyPI release ships the CLI, Django
+TradingCodex is agentic investment workflow software that runs from the user's
+workspace and local runtime by default. A PyPI release ships the CLI, Django
 service plane, generated workspace templates, Admin/Web templates, static
 assets, and MCP gateway code. It does not deploy a hosted service. Core ships
 paper execution by default; broker-specific live execution requires installed,
@@ -11,11 +12,13 @@ reviewed providers and explicit live gates.
 
 ## Release Policy
 
-The `0.2.x` release line is the OrderTicket rewrite contract for the local-first
-Python/Django harness. Order flows use central DB `OrderTicket` records
-directly; pre-release compatibility shims do not remain in the runtime package.
-The documented Web, API, CLI, MCP, generated workspace, and
-application-service surfaces are the supported contract.
+The `0.3.x` release line is the agentic judgment quality contract for the
+Python/Django harness. It keeps investment judgment reviewable, challengeable,
+source-aware, and revisitable before portfolio, risk, approval, or execution
+steps. Order flows continue to use central DB `OrderTicket` records directly;
+pre-release compatibility shims do not remain in the runtime package. The
+documented Web, API, CLI, MCP, generated workspace, and application-service
+surfaces are the supported contract.
 
 Execution status for this release line:
 
@@ -141,7 +144,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.10
+  tradingcodex==0.3.0
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -170,7 +173,7 @@ After the PyPI workflow completes:
 
 ```bash
 python3.11 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.10
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.3.0
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -264,8 +267,11 @@ Use PEP 440 versions:
 - `0.2.9` for stale service replacement and web scroll-state fixes after
   `0.2.8`
 - `0.2.10` for workflow planning and automation skill updates after `0.2.9`
-- later patch releases for compatible fixes after `0.2.10`
-- pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
+- `0.3.0` for the independent judgment-review gate, staged workflow routing
+  cleanup, Decision Quality Spine hardening, and source-aware thesis lifecycle
+  updates after `0.2.10`
+- later patch releases for compatible fixes after `0.3.0`
+- pre-releases such as `0.4.0a1`, `0.4.0b1`, or `0.4.0rc1` when preparing
   the next minor contract
 
 PyPI files are immutable. If a release has a packaging defect, publish the next