tradingcodex 0.2.2__tar.gz → 0.2.4__tar.gz

{tradingcodex-0.2.2 → tradingcodex-0.2.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.2.2
-Summary: Codex-native trading harness with a Django service plane and MCP execution boundary.
+Version: 0.2.4
+Summary: Codex-native trading harness with a Django service plane and approved action boundary.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
 Keywords: trading,django,codex,mcp,portfolio,research
@@ -59,8 +59,8 @@ Dynamic: license-file
 
 TradingCodex is a local-first Python/Django trading harness for rigorous
 Codex-assisted research, portfolio review, order-ticket checks, approvals, and
-experimental paper/stub execution. Codex coordinates the work, Django owns the
-durable service plane, and TradingCodex MCP is the executable boundary.
+experimental non-live submission checks. Codex coordinates the work, Django
+owns the durable service plane, and TradingCodex owns the executable boundary.
 
 [Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
@@ -90,11 +90,11 @@ broker actions. Live broker adapters are not shipped in the initial core.
 | Django service plane | Web, Admin, API, CLI, MCP, and generated hooks call shared application services for policy, orders, approvals, portfolio, audit, integrations, and research indexing. |
 | File-native research memory | Research markdown, role reports, source snapshots, versions, readiness labels, and handoff metadata stay readable in workspace files. |
 | Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
-| MCP execution boundary | Tools are typed, role-scoped, policy-checked, approval-aware, idempotent, adapter-gated, and audited. |
-| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, External MCP Gate metadata, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
+| 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 | Register connector profiles, inspect capability profiles, run read-only paper sync, review instrument constraints, and reconcile portfolio state. |
 | OrderTicket lifecycle | Draft, check, approve, submit, cancel, refresh, and inspect order tickets through central DB records and service-layer state transitions. |
-| External MCP Gate | Import external MCP discovery metadata, classify tool risk, scope role access, and block unsafe raw execution or secret proxy paths by default. |
+| 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. |
 
 ---
@@ -167,9 +167,10 @@ boundaries rather than on black-box automation.
 - Strong role model: one `head-manager` coordinates nine fixed specialist
   subagents and consumes accepted artifacts instead of silently redoing roles.
 - Deterministic executable boundary: every executable path follows
-  `principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit`.
-- Safety-first broker posture: live broker execution is excluded; paper, stub,
-  and reviewed test/sandbox validation remain experimental local harness flows.
+  a fixed requester, permission, policy, payload, approval, duplicate-request,
+  connection, and audit sequence.
+- Safety-first broker posture: live broker execution is excluded; paper and
+  reviewed test/sandbox validation remain experimental local harness flows.
 
 ---
 
@@ -179,8 +180,8 @@ TradingCodex is designed around handoffs:
 
 ```text
 evidence -> analysis -> valuation -> portfolio fit -> risk review
-  -> draft order -> approval receipt -> MCP submit_approved_order
-  -> adapter -> audit/postmortem
+  -> draft order -> approval receipt -> approved non-live submission
+  -> connection result -> audit/postmortem
 ```
 
 The `head-manager` maps the request, dispatches the selected role team, waits
@@ -203,7 +204,7 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 | Decision review | `valuation-analyst` | Valuation ranges, scenario assumptions, multiples, sensitivity, and decision-quality gaps. |
 | Portfolio | `portfolio-manager` | Portfolio fit, sizing, concentration, liquidity, opportunity cost, and draft order-ticket readiness. |
 | Risk | `risk-manager` | Downside, restricted-list checks, policy readiness, approval readiness, and approval receipts. |
-| Execution | `execution-operator` | Approved paper/stub execution through TradingCodex MCP only. |
+| Execution | `execution-operator` | Approved non-live submission through the TradingCodex service boundary only. |
 
 ---
 
@@ -211,7 +212,7 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 
 | Surface | Role |
 | --- | --- |
-| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, External MCP Gate, order tickets, portfolio state, and activity. |
+| 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. |
@@ -228,7 +229,7 @@ core package.
 TradingCodex blocks or constrains:
 
 - direct live broker requests
-- raw broker API calls and raw external MCP execution proxies
+- raw broker API calls and raw external source execution proxies
 - self-issued approvals
 - restricted-symbol orders
 - expired or payload-mismatched approval receipts
@@ -249,7 +250,7 @@ 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, Broker Center foundations, External MCP Gate, role-scoped MCP tools, paper/stub execution lifecycle, and Python `>=3.11,<3.15` support. |
+| Current `0.2.x` | Central-DB `OrderTicket` rewrite, Broker Center foundations, Data Sources gate, role-scoped actions, non-live execution lifecycle, and Python `>=3.11,<3.15` support. |
 | Next | Deeper validation scenarios, richer connector capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
 | Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and live broker support only after explicit product, policy, adapter, and validation work. |
 
@@ -263,7 +264,7 @@ provide investment recommendations or guarantee returns.
 | [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
 | [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
-| [Harness model](docs/harness.md) | Top-level harness model, components, guardrails, improvement, and naming rules. |
+| [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. |
 | [System architecture](docs/system-architecture.md) | Runtime planes, Django app boundaries, central DB ownership, models, and service use cases. |
@@ -278,7 +279,7 @@ Contributions use Apache-2.0 with DCO sign-off. See
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 For source changes, start with the focused validation command for the touched
-surface, then broaden as needed:
+area, then broaden as needed:
 
 ```bash
 python -m pytest

{tradingcodex-0.2.2 → tradingcodex-0.2.4}/README.md

@@ -28,8 +28,8 @@
 
 TradingCodex is a local-first Python/Django trading harness for rigorous
 Codex-assisted research, portfolio review, order-ticket checks, approvals, and
-experimental paper/stub execution. Codex coordinates the work, Django owns the
-durable service plane, and TradingCodex MCP is the executable boundary.
+experimental non-live submission checks. Codex coordinates the work, Django
+owns the durable service plane, and TradingCodex owns the executable boundary.
 
 [Quick Start](#installation) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Architecture](docs/system-architecture.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
@@ -59,11 +59,11 @@ broker actions. Live broker adapters are not shipped in the initial core.
 | Django service plane | Web, Admin, API, CLI, MCP, and generated hooks call shared application services for policy, orders, approvals, portfolio, audit, integrations, and research indexing. |
 | File-native research memory | Research markdown, role reports, source snapshots, versions, readiness labels, and handoff metadata stay readable in workspace files. |
 | Fixed-role workflows | Specialist agents own bounded questions across fundamentals, technicals, news, macro, instruments, valuation, portfolio, risk, and execution. |
-| MCP execution boundary | Tools are typed, role-scoped, policy-checked, approval-aware, idempotent, adapter-gated, and audited. |
-| Local web dashboard | Review agents, skills, strategy skills, research markdown, Broker Center, External MCP Gate metadata, order tickets, portfolio state, and activity at `127.0.0.1:48267`. |
+| 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 | Register connector profiles, inspect capability profiles, run read-only paper sync, review instrument constraints, and reconcile portfolio state. |
 | OrderTicket lifecycle | Draft, check, approve, submit, cancel, refresh, and inspect order tickets through central DB records and service-layer state transitions. |
-| External MCP Gate | Import external MCP discovery metadata, classify tool risk, scope role access, and block unsafe raw execution or secret proxy paths by default. |
+| 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. |
 
 ---
@@ -136,9 +136,10 @@ boundaries rather than on black-box automation.
 - Strong role model: one `head-manager` coordinates nine fixed specialist
   subagents and consumes accepted artifacts instead of silently redoing roles.
 - Deterministic executable boundary: every executable path follows
-  `principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit`.
-- Safety-first broker posture: live broker execution is excluded; paper, stub,
-  and reviewed test/sandbox validation remain experimental local harness flows.
+  a fixed requester, permission, policy, payload, approval, duplicate-request,
+  connection, and audit sequence.
+- Safety-first broker posture: live broker execution is excluded; paper and
+  reviewed test/sandbox validation remain experimental local harness flows.
 
 ---
 
@@ -148,8 +149,8 @@ TradingCodex is designed around handoffs:
 
 ```text
 evidence -> analysis -> valuation -> portfolio fit -> risk review
-  -> draft order -> approval receipt -> MCP submit_approved_order
-  -> adapter -> audit/postmortem
+  -> draft order -> approval receipt -> approved non-live submission
+  -> connection result -> audit/postmortem
 ```
 
 The `head-manager` maps the request, dispatches the selected role team, waits
@@ -172,7 +173,7 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 | Decision review | `valuation-analyst` | Valuation ranges, scenario assumptions, multiples, sensitivity, and decision-quality gaps. |
 | Portfolio | `portfolio-manager` | Portfolio fit, sizing, concentration, liquidity, opportunity cost, and draft order-ticket readiness. |
 | Risk | `risk-manager` | Downside, restricted-list checks, policy readiness, approval readiness, and approval receipts. |
-| Execution | `execution-operator` | Approved paper/stub execution through TradingCodex MCP only. |
+| Execution | `execution-operator` | Approved non-live submission through the TradingCodex service boundary only. |
 
 ---
 
@@ -180,7 +181,7 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 
 | Surface | Role |
 | --- | --- |
-| Product web | Agents-first review dashboard for roles, skills, research markdown, Broker Center, External MCP Gate, order tickets, portfolio state, and activity. |
+| 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. |
@@ -197,7 +198,7 @@ core package.
 TradingCodex blocks or constrains:
 
 - direct live broker requests
-- raw broker API calls and raw external MCP execution proxies
+- raw broker API calls and raw external source execution proxies
 - self-issued approvals
 - restricted-symbol orders
 - expired or payload-mismatched approval receipts
@@ -218,7 +219,7 @@ 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, Broker Center foundations, External MCP Gate, role-scoped MCP tools, paper/stub execution lifecycle, and Python `>=3.11,<3.15` support. |
+| Current `0.2.x` | Central-DB `OrderTicket` rewrite, Broker Center foundations, Data Sources gate, role-scoped actions, non-live execution lifecycle, and Python `>=3.11,<3.15` support. |
 | Next | Deeper validation scenarios, richer connector capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
 | Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and live broker support only after explicit product, policy, adapter, and validation work. |
 
@@ -232,7 +233,7 @@ provide investment recommendations or guarantee returns.
 | [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
 | [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
-| [Harness model](docs/harness.md) | Top-level harness model, components, guardrails, improvement, and naming rules. |
+| [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. |
 | [System architecture](docs/system-architecture.md) | Runtime planes, Django app boundaries, central DB ownership, models, and service use cases. |
@@ -247,7 +248,7 @@ Contributions use Apache-2.0 with DCO sign-off. See
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 For source changes, start with the focused validation command for the touched
-surface, then broaden as needed:
+area, then broaden as needed:
 
 ```bash
 python -m pytest

{tradingcodex-0.2.2 → tradingcodex-0.2.4}/docs/README.md

@@ -24,6 +24,7 @@ reference, then follow the topic-specific files for implementation-level rules.
 | [guardrails.md](./guardrails.md) | Guardrails taxonomy: guidance, enforcement, and information barriers | Guardrail classes, enforcement boundaries, information barriers, or safety taxonomy changes |
 | [improvement-loop.md](./improvement-loop.md) | Improvement taxonomy: workflow quality, research memory, file-native skill proposals, postmortems, validation feedback | Quality gates, learning loops, postmortems, skill proposal/projection, or validation feedback behavior changes |
 | [product-direction.md](./product-direction.md) | Product definition, target users, goals, non-goals, scope posture, current defaults | Product direction, release scope, default runtime, product language, or live-execution posture changes |
+| [financial-workflow-references.md](./financial-workflow-references.md) | Research-backed finance workflow and non-expert UX principles for workflow handoffs and role outputs | User-facing workflow intake, suitability/profile context, plain-English output, or professional finance method framing changes |
 | [system-architecture.md](./system-architecture.md) | Django modular monolith, central DB, app boundaries, service layer, core models, runtime planes | Django apps, DB ownership, service-layer use cases, model ownership, or runtime topology changes |
 | [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) | Product web, Django Admin, Django Ninja API, MCP endpoint, CLI, generated `./tcx` wrapper | User/admin/API/MCP/CLI surface changes, route changes, or callable tool changes |
 | [safety-policy-and-execution.md](./safety-policy-and-execution.md) | Guardrail taxonomy, policy checks, approvals, idempotency, execution lifecycle, blocked actions | Policy, permissions, approvals, adapters, execution, restricted list, secret handling, or risk gates change |
@@ -43,7 +44,7 @@ reference, then follow the topic-specific files for implementation-level rules.
 | Gateway docs remain stable | `core-concepts-and-rules.md` stays as the stable entrypoint even when details move into topic files. |
 | Implementation verifies docs | Implementation does not replace the docs. If implementation reveals a durable rule, document it. |
 | Product language is English | TradingCodex product copy, generated workspace guidance, Admin UI, CLI help, and durable docs are written in English. |
-| Product web is review-first | The `/` web app redirects to the agents-first skill browser and can prepare starter prompts, but does not spawn agents, approve orders, or execute orders. |
+| Product web is review-first | The `/` web app opens on the workflow planner and can preview handoffs, but 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. |
 
 ## Change Checklist
@@ -52,6 +53,7 @@ reference, then follow the topic-specific files for implementation-level rules.
 | --- | --- |
 | 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` |
 | Product scope, non-goals, or default runtime | `product-direction.md`, `harness.md` |
+| Financial workflow intake, non-expert UX, suitability/profile context, or plain-English finance output | `financial-workflow-references.md`, `interfaces-and-surfaces.md`, `roles-skills-and-workflows.md` |
 | Django apps, models, service-layer contracts, or DB ownership | `system-architecture.md` |
 | Product web, Admin, REST, MCP, CLI, or wrapper behavior | `interfaces-and-surfaces.md` |
 | Guardrails, policy, permission, approval, execution, adapter, or secret boundary | `guardrails.md`, `safety-policy-and-execution.md`, `core-concepts-and-rules.md` |

{tradingcodex-0.2.2 → tradingcodex-0.2.4}/docs/components.md

@@ -43,16 +43,16 @@ paths clear.
 | `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` |
-| `external-mcp-proxy-gate` | Registers external MCP connections, imports metadata, classifies risk, manages lifecycle/review state, and blocks unsafe direct proxy paths. | `guardrail.enforcement`, `guardrail.information_barrier` |
+| `external-mcp-proxy-gate` | Registers external MCP connections, imports metadata, classifies risk, manages lifecycle/review state, and blocks unsafe direct connection paths. | `guardrail.enforcement`, `guardrail.information_barrier` |
 | `broker-center` | Normalizes native broker connector profiles, read-only account discovery, sync runs, instrument constraints, and order-translation previews. | `guardrail.enforcement`, `improvement.workflow_quality` |
 | `secret-wall` | Blocks raw broker secrets from workspace files, prompts, shell paths, and role context. | `guardrail.enforcement`, `guardrail.information_barrier` |
 | `policy-and-restricted-list` | Evaluates principals, capabilities, explicit deny rules, restricted symbols, and limits. | `guardrail.enforcement` |
 | `approval-gate` | Validates order tickets, JSON order inputs, and approval receipts before execution-sensitive action. | `guardrail.enforcement` |
-| `execution-boundary` | Keeps execution behind MCP allowlists, approval, idempotency, adapter, and audit checks. | `guardrail.enforcement`, `guardrail.information_barrier` |
+| `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, and executions into improvements. | `improvement.postmortems`, `improvement.validation_feedback` |
-| `paper-execution` | Provides experimental local paper and stub adapters behind the execution boundary. | `guardrail.enforcement` |
+| `paper-execution` | Provides experimental local paper and validation-only execution paths behind the approved action boundary. | `guardrail.enforcement` |
 
 ## Runtime Surfaces
 

{tradingcodex-0.2.2 → tradingcodex-0.2.4}/docs/core-concepts-and-rules.md

@@ -7,9 +7,9 @@ the detailed source documents rather than repeating every rule. Use
 ## One-Line Product Definition
 
 TradingCodex is a Python/Django-native trading harness that lets an investor
-use Codex for research, decision support, approvals, and stub/paper execution
-while ensuring every executable action crosses a deterministic Django service
-layer and TradingCodex MCP enforcement boundary.
+use Codex for research, decision support, approvals, and non-live validation
+while ensuring every executable action crosses deterministic Django service
+checks.
 
 ## Core Principles
 
@@ -19,8 +19,8 @@ layer and TradingCodex MCP enforcement boundary.
 | Django service layer is canonical | Product web, Admin, REST, MCP, and CLI call the same application services. | Do not duplicate policy, order, approval, execution, research indexing, or audit logic per interface. |
 | Central DB is the runtime ledger | Execution-sensitive mutable state lives in the user-level central Django DB. | Do not use workspace paths as portfolio/order/account ledgers. |
 | Workspace files are Codex-native SOT | Agent config, skill bundles, and research handoff markdown live in workspace files. | Codex-visible state must be projected to files rather than hidden only in DB rows. |
-| MCP owns executable boundary | Executable action boundaries belong to TradingCodex MCP/service-layer paths. | Raw API keys must not appear in workspace files, shell output, prompts, API responses, MCP responses, or audit output. |
-| Enforcement is deterministic | Blocking decisions are reproducible code/policy decisions. | Final order paths revalidate policy, schema, approval, idempotency, adapter, and audit. |
+| Service gates own executable actions | Executable action boundaries belong to TradingCodex service-layer and MCP paths. | Raw API keys must not appear in workspace files, shell output, prompts, API responses, MCP responses, or audit output. |
+| Enforcement is deterministic | Blocking decisions are reproducible code/policy decisions. | Final order paths revalidate policy, payload shape, approval, duplicate-request status, connection, and audit. |
 | Capability is an allowlist | Permission is explicit and narrow. | Allowing one action does not imply policy write, secret read, or cash movement. |
 | Information barriers control knowledge flow | Roles receive only the information they need. | Maintain research, execution, policy, and secret walls. |
 | Improvement loops raise work quality | The harness should improve investment work, not only block bad actions. | Manage skills, schemas, workflows, checklists, validation feedback, and postmortems together. |
@@ -91,7 +91,7 @@ subagents. Detailed responsibilities live in
 | analyst roles | research, evidence, valuation, market/instrument context | order approval, execution, secret read |
 | `portfolio-manager` | portfolio fit and draft order ticket | self-approval, execution, arbitrary policy change |
 | `risk-manager` | risk review, policy review, approval receipt | order drafting, execution, arbitrary policy change |
-| `execution-operator` | submit approved orders through TradingCodex MCP | raw broker API, secret read, policy change |
+| `execution-operator` | submit approved non-live orders through the TradingCodex service boundary | raw broker API, secret read, policy change |
 
 Handoff states are `accepted`, `revise`, `blocked`, or `waiting`. Only accepted
 artifacts move downstream. `head-manager` may synthesize accepted outputs and
@@ -104,17 +104,18 @@ Detailed execution rules live in
 
 ```text
 evidence -> analysis -> portfolio fit -> draft order -> risk review
-  -> approval receipt -> MCP submit_approved_order -> adapter -> audit/postmortem
+  -> approval receipt -> approved submit action -> connection -> audit/postmortem
 ```
 
 Every executable use case follows:
 
 ```text
-principal -> capability -> policy -> schema -> approval/idempotency -> adapter -> audit
+requester -> permission -> policy -> payload validation -> approval/duplicate-request check -> connection -> audit
 ```
 
-Paper/stub execution remains experimental local harness behavior. Live broker
-adapters remain disabled and unimplemented in the initial core.
+Paper and validation-only execution paths remain experimental local harness
+behavior. Live broker adapters remain disabled and unimplemented in the initial
+core.
 
 ## Research Memory Snapshot
 
@@ -133,7 +134,7 @@ Detailed research rules live in
 
 | Rule | Application |
 | --- | --- |
-| Durable rule change requires docs update | Product direction, safety rules, role responsibilities, execution boundary, artifact contracts, and generated behavior require docs updates. |
+| Durable rule change requires docs update | Product direction, safety rules, role responsibilities, approved action boundary, artifact contracts, and generated behavior require docs updates. |
 | Docs are source of truth | Gateway and topic documents record intent above implementation. If implementation differs, decide explicitly which side changes. |
 | Avoid hidden policy drift | Do not hide durable rules only in templates, tests, MCP, hooks, prompts, or skills. |
 | Keep product language English | Do not add non-English durable copy to docs, generated workspace guidance, Admin UI, CLI help, role prompts, or examples. |

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

@@ -19,10 +19,10 @@ application-service surfaces are the supported contract.
 Execution status for this release line:
 
 - live broker execution is excluded
-- paper/stub execution code remains in the package for local harness tests
-- paper/stub execution is experimental and not production trading
-- execution MCP tools must stay behind policy, approval, idempotency, adapter,
-  and audit checks
+- paper and validation-only execution code remains in the package for local harness tests
+- non-live execution is experimental and not production trading
+- execution MCP tools must stay behind policy, approval, duplicate-request,
+  connection, and audit checks
 
 ## Maintainer Prerequisites
 
@@ -140,7 +140,7 @@ python3.11 -m venv /tmp/tcx-testpypi
 /tmp/tcx-testpypi/bin/pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  tradingcodex==0.2.2
+  tradingcodex==0.2.4
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -169,7 +169,7 @@ After the PyPI workflow completes:
 
 ```bash
 python3.11 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.2
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.4
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -204,6 +204,30 @@ TradingCodex has two update layers:
   generated files, generated indexes, project MCP config, hook scripts, and
   central DB schema
 
+Generated workspace `./tcx update` normally refreshes through `uvx` first so
+stale recorded Python paths do not rewrite templates. In restricted Codex
+permissions, `head-manager` should not run the update itself because it rewrites
+protected `.codex` prompt/config/hook surfaces. When the package is already
+installed and Codex startup health reports `workspace_update_allowed=true`,
+`head-manager` should tell the user to switch to full access plus TradingCodex
+build mode, or run the workspace-only path from a terminal:
+
+```bash
+./tcx update --skip-refresh
+```
+
+`head-manager` may run the update directly only when
+`update_status.can_self_update=true`, which requires Codex full access,
+unexpired TradingCodex build mode, and an explicit user request. After a
+self-update it must stop and tell the user to fully restart Codex. The terminal
+path avoids package-cache or user-tool writes and keeps self-modifying `.codex`
+prompt/config/hook updates outside a restricted active Codex agent sandbox.
+Generated Codex config declares the bounded `~/.tradingcodex` writable root so
+central DB migrations, lock files, and update preferences can still work
+without disabling the sandbox when the active Codex surface honors
+project-scoped sandbox roots. If a package update is required first, the user
+should run the package-refresh command from a terminal instead.
+
 `tcx update` must preserve `.tradingcodex/workspace.json` identity fields,
 including `workspace_id` and active profile. It may overwrite generated paths
 owned by `workspace_templates/modules/*/files`, and it must not overwrite
@@ -223,7 +247,11 @@ Use PEP 440 versions:
   migration, generated workspace smoke checks, and release e2e checks are stable
 - `0.2.1` for Python `>=3.11,<3.15` support and clone-free setup guidance
 - `0.2.2` for dashboard startup behavior fixes after `0.2.1`
-- later patch releases for compatible fixes after `0.2.2`
+- `0.2.3` for workflow-planner UX, fixed strategy authoring, profile-scoped
+  ticket isolation, workspace-scoped transition audit, and startup/status fixes
+- `0.2.4` for the operate/build/execution plane rewrite, compact startup
+  context, build-mode updates, and connector scaffold workflow
+- later patch releases for compatible fixes after `0.2.4`
 - pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
   the next minor contract
 
@@ -241,5 +269,5 @@ This PyPI release does not deploy:
 - official commercial/verified adapter packs
 
 Those surfaces require separate product decisions, separate documentation, and
-the same service-layer policy, approval, adapter, idempotency, and audit
+the same service-layer policy, approval, duplicate-request, connection, and audit
 boundary.

tradingcodex-0.2.4/docs/financial-workflow-references.md

@@ -0,0 +1,152 @@
+# Financial Workflow References
+
+TradingCodex should stay Codex-native while making expert financial workflow
+steps legible to non-expert users. Product surfaces should translate a plain
+request into a role workflow, show what is still blocked, and ask for missing
+investor context before recommendation, sizing, approval, or execution.
+This is the product's safe intuition-led workflow: a user can start with a
+rough market intuition, but TradingCodex turns it into evidence gathering,
+profile questions, role handoffs, and explicit next allowed actions instead of
+jumping straight to a trade.
+Short ticker-first intuition such as "TSLA feels interesting" or
+"AAPL seems cheap" should therefore route to a research-first workflow unless
+the user explicitly asks for valuation, portfolio fit, recommendation, order
+drafting, approval, or execution.
+
+## Workflow Principles
+
+| Principle | Product implication | Reference |
+| --- | --- | --- |
+| Portfolio risk comes before single-security action | Portfolio and risk lanes ask for objective, horizon, risk tolerance, liquidity needs, holdings, and constraints before recommendation, sizing, approval, or execution. | FINRA Rule 2111 customer investment profile and suitability guidance |
+| Retail recommendations require investor-profile context | Decision-support workflows should expose missing profile fields rather than producing blanket recommendations. | SEC Regulation Best Interest staff bulletin on care obligations |
+| Asset allocation, diversification, and rebalancing are the baseline risk frame | Research and portfolio outputs should separate single-name evidence from portfolio exposure, concentration, and rebalancing context. | SEC Investor.gov asset allocation/diversification/rebalancing guidance |
+| Mean-variance and factor thinking are analytical tools, not automatic advice | Valuation and portfolio roles can use expected return, variance, covariance, and factor exposure concepts, but must expose assumptions and uncertainty. | Markowitz (1952); Fama and French (1993) |
+| Strategic allocation depends on horizon and risk tolerance | Long-horizon workflows should treat time horizon and loss capacity as required context, not afterthoughts. | Campbell and Viceira (2002) |
+| Investment policy is objectives plus constraints | Portfolio workflows should frame recommendations against return/risk objectives, liquidity, time horizon, tax, legal/regulatory, and unique constraints. | CFA Institute investment policy statement guidance |
+| Planning is a process, not a one-shot answer | Beginner-facing UX should show workflow stage, next evidence needed, and blocked actions before presenting outputs as advice. | CFP Board financial planning process |
+| Each workflow should make later workflows easier | Role artifacts should preserve reusable context summaries, reader summaries, source snapshots, missing-evidence notes, and improvement proposals instead of making future agents rediscover the same gaps. | Every compound engineering guide; Will Larson commentary |
+| Agentic work should be a bounded loop, not open-ended autonomy | TradingCodex workflows may repeat evidence gathering, artifact verification, synthesis, and memory capture, but every lane must expose stop conditions and blocked actions. | Recent loop-engineering practice across Codex, Claude Code, OpenClaw, and memory-layer frameworks |
+| Loop reliability depends on the verifier | Every workflow lane should name what gets checked after each pass: artifact quality, source freshness, profile gaps, and blocked actions. Failed checks return `revise`, `blocked`, or `waiting` rather than widening the lane. | Addy Osmani loop-engineering framing; recent verifier/budget loop guidance |
+| Financial agent teams need explicit opposition | Decision-support synthesis should test the favorable case against a bearish or skeptical case, stale data, missing profile context, policy conflicts, and selected-strategy conflicts before naming a decision state. | TradingAgents bull/bear researcher debate; risk management team |
+| AI-assisted finance must stay auditable and bounded | Agent workflows should keep role boundaries, source/as-of posture, handoff states, policy gates, duplicate-request controls, and audit evidence visible. | NIST AI Risk Management Framework |
+| AI/ML in capital markets needs governance, testing, monitoring, data quality, and explainability | Agentic workflow features should keep dispatch, role outputs, source quality, and audit trails inspectable. | IOSCO AI/ML guidance for market intermediaries and asset managers |
+| Plain English increases investor comprehension without deleting complexity | User-facing web output should show plain-language workflow summaries first, with professional evidence and caveats behind them. | SEC Plain English Handbook |
+
+## Source Map
+
+| Source | TradingCodex design rule |
+| --- | --- |
+| [FINRA Rule 2111](https://www.finra.org/rules-guidance/rulebooks/finra-rules/2111) | Investor-profile fields are first-class workflow inputs: objective, other investments, tax/account constraints, horizon, liquidity, and risk tolerance. |
+| [SEC Reg BI care-obligation staff bulletin](https://www.sec.gov/about/divisions-offices/division-trading-markets/broker-dealers/staff-bulletin-standards-conduct-broker-dealers-investment-advisers-care-obligations) | Decision-support lanes must expose missing retail-investor context before recommendation, sizing, or order work. |
+| [SEC Investor.gov asset allocation guidance](https://www.investor.gov/introduction-investing/getting-started/asset-allocation) | Single-name research should stay separate from portfolio allocation, diversification, and rebalancing checks. |
+| [Markowitz, "Portfolio Selection" (1952)](https://ideas.repec.org/a/bla/jfinan/v7y1952i1p77-91.html) | Portfolio roles should treat expected return, variance, covariance, and diversification as analytical lenses, not as automatic trade instructions. |
+| [Fama and French, "Common risk factors in the returns on stocks and bonds" (1993)](https://ideas.repec.org/a/eee/jfinec/v33y1993i1p3-56.html) | Research and portfolio outputs should separate issuer-specific thesis claims from factor, market, maturity, and default-risk exposure. |
+| [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) | Agentic finance workflows need visible governance, context mapping, measurement, and risk-management checkpoints. |
+| [NIST AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) | Prompt gates, handoff states, quality checks, and audit outputs should map to govern, map, measure, and manage functions. |
+| [IOSCO AI/ML report for market intermediaries and asset managers](https://www.iosco.org/library/pubdocs/pdf/IOSCOPD684.pdf) | AI-assisted capital-markets features need governance, testing, monitoring, data-quality controls, explainability, and outsourcing/third-party oversight posture. |
+| [SEC Plain English Handbook](https://www.sec.gov/pdf/handbook.pdf) | User-facing screens should start with plain-English workflow meaning before professional evidence, assumptions, caveats, and artifacts. |
+| [Every, "Compound Engineering"](https://every.to/guides/compound-engineering) | Engineering work should teach the system reusable capabilities; TradingCodex applies this by making role outputs preserve compact context, reader summaries, source posture, and missing-evidence notes for future workflows. |
+| [Will Larson, "Learning from Every's Compound Engineering"](https://lethain.com/everyinc-compound-engineering/) | The useful pattern is separating research/planning, work, review, and compounding lessons; TradingCodex mirrors that with starter intake, role artifacts, quality checks, and improvement proposals. |
+| [Addy Osmani, "Loop Engineering"](https://addyosmani.com/blog/loop-engineering/) | A useful agentic loop combines automations, isolated workspaces, skills, connectors, subagents, and durable external memory; TradingCodex maps these to prompt gates, fixed subagents, MCP/service boundaries, artifacts, and generated workspace state. |
+| [Business Insider, "Forget prompt engineering: Loop engineering is all the rage now"](https://www.businessinsider.com/what-are-loops-ai-engineering-tips-2026-6) | Current loop-engineering discourse emphasizes designing recurring systems that prompt agents, with cost and oversight tradeoffs; TradingCodex exposes loop controls and token/context budgets rather than unlimited autonomy. |
+| [Anthropic Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills) | Recent agent tooling exposes loops through reusable skills, bundled `/loop`, subagent execution, and dynamic context; TradingCodex mirrors the reusable-skill and fixed-subagent pattern without depending on Claude Code. |
+| [Anthropic Claude Code hooks docs](https://docs.anthropic.com/en/docs/claude-code/hooks-guide) | Agent hooks can verify conditions before allowing a workflow to continue; TradingCodex maps this to hook gates, context-audit, quality-check, and handoff states. |
+| [OpenClaw](https://github.com/openclaw/openclaw) | Agent control planes show the value and risk of persistent assistant loops across devices/channels; TradingCodex keeps loops workspace-scoped, auditable, and blocked from secrets or execution unless service gates allow it. |
+| [Mem0, "Loop Engineering for AI Agents: Memory-First Design"](https://mem0.ai/blog/loop-engineering-for-ai-agents-memory-first-design) | Memory-first loop design separates durable memory from a single chat context; TradingCodex uses workspace-native artifacts, source snapshots, context summaries, and generated manifests as its durable memory layer. |
+| [TradingAgents repository](https://github.com/tauricresearch/tradingagents) and [TradingAgents paper](https://arxiv.org/abs/2412.20138) | The useful pattern is not autonomous execution, but explicit role specialization, bull/bear researcher debate, trader synthesis, and risk review. TradingCodex adapts this as challenge review before synthesis while keeping order, approval, and execution behind service gates. |
+
+## Workflow Handoff Intake Contract
+
+The workflow planner is a local preparation surface that produces a Codex
+handoff. It must not spawn agents, produce investment analysis, approve orders,
+or execute trades. It should:
+
+- classify the request into a workflow lane and investment universe
+- translate rough investor intuition into a plain-English working hypothesis
+  and safety boundary
+- show the stage order in plain language, such as evidence, valuation,
+  portfolio fit, risk review, approved action boundary, and synthesis
+- show stage exit criteria so users can see what must be true before the
+  workflow moves forward
+- keep lane loop controls, judgment controls, strategy baseline, and method
+  lenses available in a review section so users can inspect professional
+  reasoning without making the first screen feel like an expert checklist
+- expose method lenses such as suitability/profile, portfolio risk, factor
+  exposure, execution-boundary, or AI-governance references with a short
+  plain-language reason each lens matters
+- show the selected role team in readable labels and explain why each role is
+  needed for the lane
+- show blocked actions before artifacts exist, with a plain-language reason
+  for each blocked action
+- show the next allowed actions so users can distinguish safe preparation from
+  blocked order, approval, or execution paths
+- ask for investor profile context when the lane reaches decision support,
+  portfolio fit, order drafting, approval, or execution
+- reuse answered active-profile investor context so users are not asked the
+  same suitability/profile question every time
+- translate missing profile fields into direct user questions, with a short
+  reason each answer is required
+- keep the generated Codex prompt compact enough for native dispatch and place
+  the raw prompt in a handoff section rather than making it the first-read UX
+- instruct agents to write plain-English first, then professional evidence,
+  assumptions, and caveats
+- instruct agents to preserve reusable context, source snapshots, missing
+  evidence, tests, or improvement proposals when a lesson should compound into
+  future workflows
+
+Loop engineering applies only inside the workflow boundary selected at intake.
+TradingCodex can loop over research discovery, artifact quality, stale-source
+checks, profile gaps, and synthesis revisions. It must not let a loop widen
+itself into recommendation, order drafting, approval, execution, raw broker API,
+or secret handling. Those transitions require explicit user intent and the
+separate service-layer gates already documented in the harness.
+
+When no active user-approved strategy exists, TradingCodex should not invent a
+fixed contract. It should state that the current request uses generated
+TradingCodex rules, explicit user constraints, investor-profile context, and
+temporary scenario assumptions. A durable strategy is created only through the
+strategy authoring path, not as a side effect of analysis.
+
+## Source Notes
+
+- SEC Investor.gov describes asset allocation, diversification, and
+  rebalancing as core risk-management practices for individual investors.
+- SEC Reg BI staff guidance describes investment-profile factors such as
+  financial situation, needs, investments, tax status, time horizon, liquidity
+  needs, risk tolerance, investment experience, objectives, and goals.
+- FINRA suitability materials define customer-specific suitability around the
+  customer's investment profile, including objectives, risk tolerance, horizon,
+  liquidity needs, and other customer-specific factors.
+- Markowitz's portfolio-selection framework is the product reason portfolio
+  review treats variance, covariance, and diversification as required context
+  before action.
+- Fama-French factor framing is the product reason research outputs must
+  distinguish company-specific claims from market, size, value, maturity, and
+  default-risk exposures.
+- CFA Institute IPS guidance frames investment strategy around overall
+  financial plans, objectives, risk tolerance, preferences, and constraints.
+- CFP Board practice standards treat planning as a collaborative process that
+  integrates personal and financial circumstances before advice.
+- The SEC Plain English Handbook frames plain English as deciding what
+  investors need to know, then presenting complex information clearly.
+- NIST AI RMF emphasizes governing, mapping, measuring, and managing AI risks
+  across real-world use, including transparency and documentation concerns.
+- IOSCO AI/ML guidance highlights governance and oversight, algorithm
+  development/testing/monitoring, data quality and bias, transparency and
+  explainability, outsourcing, and ethical concerns for capital-markets AI.
+- Addy Osmani frames loop engineering as designing the system that prompts
+  agents, built from automations, worktrees, skills, connectors, subagents, and
+  memory outside a single conversation.
+- Recent loop-engineering frameworks converge on recurring agent triggers,
+  reusable procedures, subagent decomposition, verification hooks, connectors,
+  and durable memory. TradingCodex should stay framework-agnostic: use these
+  ideas through its own Codex-native prompt gates, skills, MCP/service boundary,
+  context-audit, role artifacts, and explicit human approval gates.
+- The verifier is the bottleneck in a useful loop. TradingCodex therefore keeps
+  loop controls tied to source freshness, artifact quality, profile gaps, and
+  blocked actions rather than letting the agent repeat work until it invents a
+  broader mandate.
+- TradingAgents uses specialized analysts, bull and bear researchers, trader
+  synthesis, and risk management. TradingCodex borrows the opposition and risk
+  review structure, but does not let that structure self-approve, self-execute,
+  or silently create a user strategy.