tradingcodex 0.2.0__tar.gz → 0.2.1__tar.gz

{tradingcodex-0.2.0 → tradingcodex-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.2.0
+Version: 0.2.1
 Summary: Codex-native trading harness with a Django service plane and MCP execution boundary.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
@@ -10,9 +10,12 @@ Classifier: Framework :: Django
 Classifier: Framework :: Django :: 5.2
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business :: Financial :: Investment
-Requires-Python: <3.15,>=3.14
+Requires-Python: <3.15,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
@@ -26,6 +29,13 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Dynamic: license-file
 
+> [!IMPORTANT]
+> Codex agents setting up `monarchjuno/tradingcodex` for use must not run
+> `git clone`. In the empty target workspace, run the packaged CLI:
+> `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`
+> Clone this repository only when the user explicitly asks to develop
+> TradingCodex source code.
+
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
 </p>
@@ -35,7 +45,7 @@ Dynamic: license-file
   <a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="Release" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=release"></a>
   <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
-  <img alt="Python" src="https://img.shields.io/badge/python-3.14-3776AB?logo=python&logoColor=white">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
 </div>
 
 <div align="center">
@@ -63,6 +73,53 @@ It is not an autonomous trading bot. Codex coordinates and explains the work;
 Django owns durable state and policy; TradingCodex MCP is the only executable
 agent boundary; live broker adapters are not shipped in the initial core.
 
+## Quick Start
+
+Codex app current-workspace one-liner: run this from the empty workspace you
+want to turn into TradingCodex. Do not run `git clone` for setup; cloning
+`monarchjuno/tradingcodex` is only for developing TradingCodex source code.
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+This installs/runs the TradingCodex CLI with a compatible Python
+(`>=3.11,<3.15`), attaches the harness to the current workspace, and runs the
+smoke check. Then fully quit and restart Codex, open the generated workspace,
+and start a new thread so project MCP config is reloaded. When TradingCodex MCP
+autostarts the local service, the dashboard is available at
+`http://127.0.0.1:48267/`.
+
+Agents and install helpers do not invent a default workspace path. If the
+target path is not supplied and the user did not say "current workspace", ask
+before creating or attaching a workspace.
+
+Start an orchestrated Codex workflow from the generated workspace:
+
+```text
+$orchestrate-workflow analyze Apple with public equity research, valuation, portfolio, and risk review
+```
+
+For repeated workspace creation, install the CLI as a user-level tool:
+
+```bash
+uv tool install tradingcodex
+uv tool update-shell
+cd /path/to/target-workspace
+tcx attach .
+./tcx doctor
+```
+
+See [installation.md](https://github.com/monarchjuno/tradingcodex/blob/main/installation.md)
+for GitHub-main installs, direct `uvx`, MCP/service details, and additional
+smoke checks.
+
+Update an existing generated workspace after a package release:
+
+```bash
+uvx --refresh --from tradingcodex tcx update .
+```
+
 ## Product Concept
 
 TradingCodex exists because serious Codex-assisted investment work should not
@@ -88,7 +145,7 @@ execution-sensitive state lives in the central local runtime DB:
 
 ## What TradingCodex Does
 
-TradingCodex `0.2.0` provides:
+TradingCodex `0.2.1` provides:
 
 - A generated Codex workspace with fixed role topology, project-scoped MCP,
   local wrappers, workspace manifest, generated policy/config files, and
@@ -107,9 +164,9 @@ TradingCodex `0.2.0` provides:
   role boundaries.
 - Policy, restricted-symbol, approval, order, execution, portfolio, MCP, and
   audit services behind a shared Django application layer.
-- Broker Center foundations: broker connections, broker accounts, read-only
-  paper sync, external MCP broker discovery import, and reconciliation
-  summaries behind the service layer.
+- Broker Center foundations: broker connections, native connector capability
+  profiles, broker accounts, read-only paper sync, external MCP discovery
+  import when needed, and reconciliation summaries behind the service layer.
 - Canonical Order Ticket foundations: natural-language or structured draft
   tickets, schema/policy/cash-position/broker validation checks, state-machine
   events, exact approval-scope binding, broker order timeline, and paper fills.
@@ -124,66 +181,6 @@ TradingCodex `0.2.0` provides:
   classifies tool risk, scopes role access, and blocks unsafe direct proxy
   paths by default.
 
-## Quick Start
-
-Choose an empty target directory for the generated Codex workspace. Source
-checkouts of this repository are for TradingCodex development; generated
-TradingCodex workspaces are separate Codex projects.
-
-Agents and install helpers do not invent a default workspace path. If the
-target path is not supplied, ask the user before creating or attaching a
-workspace.
-
-Install TradingCodex and attach it to a user-selected workspace:
-
-```bash
-mkdir -p /path/to/target-workspace
-cd /path/to/target-workspace
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- .
-```
-
-Run the smoke check:
-
-```bash
-./tcx doctor
-```
-
-After installation, fully quit and restart Codex, then open the generated
-workspace and start from a new thread so project MCP config is reloaded. When
-TradingCodex MCP autostarts the local service, the dashboard is available at:
-
-```text
-http://127.0.0.1:48267/
-```
-
-Start an orchestrated Codex workflow from the generated workspace:
-
-```text
-$orchestrate-workflow analyze Apple with public equity research, valuation, portfolio, and risk review
-```
-
-For repeated workspace creation, install the CLI as a user-level tool:
-
-```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
-uv tool update-shell
-cd /path/to/target-workspace
-tcx attach .
-./tcx doctor
-```
-
-See [installation.md](https://github.com/monarchjuno/tradingcodex/blob/main/installation.md)
-for GitHub-main installs, direct `uvx`, MCP/service details, and additional
-smoke checks.
-
-Update an existing generated workspace after a package release:
-
-```bash
-cd /path/to/target-workspace
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- --update .
-```
-
 ## Local Web Dashboard
 
 TradingCodex includes a local Django web surface so users do not have to inspect
@@ -289,7 +286,8 @@ Important boundaries:
 - REST/Admin/CLI/MCP call shared Django service functions.
 - Role MCP allowlists are narrow: `head-manager` cannot submit orders,
   `risk-manager` owns approvals, and `execution-operator` owns execution calls.
-- Paper/stub execution remains experimental.
+- Paper/stub and reviewed test/sandbox validation execution remain
+  experimental and non-live.
 - Live broker adapters are not shipped in the initial core.
 - Raw broker secrets must not be stored in this repository or generated
   workspaces.
@@ -311,10 +309,11 @@ labels such as `research-only`, `screen-grade`, `not-decision-ready`, or
 
 ## Release Status
 
-`0.2.0` is the OrderTicket rewrite release for the generated workspace, Python
-CLI, Django service plane, product web, MCP boundary, and documentation set.
-The package still uses an alpha development classifier because live broker
-adapters and hosted service modes are intentionally outside the initial core.
+`0.2.1` is a compatibility patch on the `0.2.x` OrderTicket rewrite release
+line for the generated workspace, Python CLI, Django service plane, product
+web, MCP boundary, and documentation set. The package still uses an alpha
+development classifier because live broker adapters and hosted service modes
+are intentionally outside the initial core.
 
 ## Documentation
 

{tradingcodex-0.2.0 → tradingcodex-0.2.1}/README.md

@@ -1,3 +1,10 @@
+> [!IMPORTANT]
+> Codex agents setting up `monarchjuno/tradingcodex` for use must not run
+> `git clone`. In the empty target workspace, run the packaged CLI:
+> `uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor`
+> Clone this repository only when the user explicitly asks to develop
+> TradingCodex source code.
+
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
 </p>
@@ -7,7 +14,7 @@
   <a href="https://github.com/monarchjuno/tradingcodex/releases"><img alt="Release" src="https://img.shields.io/github/v/release/monarchjuno/tradingcodex?include_prereleases&label=release"></a>
   <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
-  <img alt="Python" src="https://img.shields.io/badge/python-3.14-3776AB?logo=python&logoColor=white">
+  <img alt="Python" src="https://img.shields.io/badge/python-3.11--3.14-3776AB?logo=python&logoColor=white">
 </div>
 
 <div align="center">
@@ -35,6 +42,53 @@ It is not an autonomous trading bot. Codex coordinates and explains the work;
 Django owns durable state and policy; TradingCodex MCP is the only executable
 agent boundary; live broker adapters are not shipped in the initial core.
 
+## Quick Start
+
+Codex app current-workspace one-liner: run this from the empty workspace you
+want to turn into TradingCodex. Do not run `git clone` for setup; cloning
+`monarchjuno/tradingcodex` is only for developing TradingCodex source code.
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+This installs/runs the TradingCodex CLI with a compatible Python
+(`>=3.11,<3.15`), attaches the harness to the current workspace, and runs the
+smoke check. Then fully quit and restart Codex, open the generated workspace,
+and start a new thread so project MCP config is reloaded. When TradingCodex MCP
+autostarts the local service, the dashboard is available at
+`http://127.0.0.1:48267/`.
+
+Agents and install helpers do not invent a default workspace path. If the
+target path is not supplied and the user did not say "current workspace", ask
+before creating or attaching a workspace.
+
+Start an orchestrated Codex workflow from the generated workspace:
+
+```text
+$orchestrate-workflow analyze Apple with public equity research, valuation, portfolio, and risk review
+```
+
+For repeated workspace creation, install the CLI as a user-level tool:
+
+```bash
+uv tool install tradingcodex
+uv tool update-shell
+cd /path/to/target-workspace
+tcx attach .
+./tcx doctor
+```
+
+See [installation.md](https://github.com/monarchjuno/tradingcodex/blob/main/installation.md)
+for GitHub-main installs, direct `uvx`, MCP/service details, and additional
+smoke checks.
+
+Update an existing generated workspace after a package release:
+
+```bash
+uvx --refresh --from tradingcodex tcx update .
+```
+
 ## Product Concept
 
 TradingCodex exists because serious Codex-assisted investment work should not
@@ -60,7 +114,7 @@ execution-sensitive state lives in the central local runtime DB:
 
 ## What TradingCodex Does
 
-TradingCodex `0.2.0` provides:
+TradingCodex `0.2.1` provides:
 
 - A generated Codex workspace with fixed role topology, project-scoped MCP,
   local wrappers, workspace manifest, generated policy/config files, and
@@ -79,9 +133,9 @@ TradingCodex `0.2.0` provides:
   role boundaries.
 - Policy, restricted-symbol, approval, order, execution, portfolio, MCP, and
   audit services behind a shared Django application layer.
-- Broker Center foundations: broker connections, broker accounts, read-only
-  paper sync, external MCP broker discovery import, and reconciliation
-  summaries behind the service layer.
+- Broker Center foundations: broker connections, native connector capability
+  profiles, broker accounts, read-only paper sync, external MCP discovery
+  import when needed, and reconciliation summaries behind the service layer.
 - Canonical Order Ticket foundations: natural-language or structured draft
   tickets, schema/policy/cash-position/broker validation checks, state-machine
   events, exact approval-scope binding, broker order timeline, and paper fills.
@@ -96,66 +150,6 @@ TradingCodex `0.2.0` provides:
   classifies tool risk, scopes role access, and blocks unsafe direct proxy
   paths by default.
 
-## Quick Start
-
-Choose an empty target directory for the generated Codex workspace. Source
-checkouts of this repository are for TradingCodex development; generated
-TradingCodex workspaces are separate Codex projects.
-
-Agents and install helpers do not invent a default workspace path. If the
-target path is not supplied, ask the user before creating or attaching a
-workspace.
-
-Install TradingCodex and attach it to a user-selected workspace:
-
-```bash
-mkdir -p /path/to/target-workspace
-cd /path/to/target-workspace
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- .
-```
-
-Run the smoke check:
-
-```bash
-./tcx doctor
-```
-
-After installation, fully quit and restart Codex, then open the generated
-workspace and start from a new thread so project MCP config is reloaded. When
-TradingCodex MCP autostarts the local service, the dashboard is available at:
-
-```text
-http://127.0.0.1:48267/
-```
-
-Start an orchestrated Codex workflow from the generated workspace:
-
-```text
-$orchestrate-workflow analyze Apple with public equity research, valuation, portfolio, and risk review
-```
-
-For repeated workspace creation, install the CLI as a user-level tool:
-
-```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
-uv tool update-shell
-cd /path/to/target-workspace
-tcx attach .
-./tcx doctor
-```
-
-See [installation.md](https://github.com/monarchjuno/tradingcodex/blob/main/installation.md)
-for GitHub-main installs, direct `uvx`, MCP/service details, and additional
-smoke checks.
-
-Update an existing generated workspace after a package release:
-
-```bash
-cd /path/to/target-workspace
-curl -fsSL https://raw.githubusercontent.com/monarchjuno/tradingcodex/main/install.sh | sh -s -- --update .
-```
-
 ## Local Web Dashboard
 
 TradingCodex includes a local Django web surface so users do not have to inspect
@@ -261,7 +255,8 @@ Important boundaries:
 - REST/Admin/CLI/MCP call shared Django service functions.
 - Role MCP allowlists are narrow: `head-manager` cannot submit orders,
   `risk-manager` owns approvals, and `execution-operator` owns execution calls.
-- Paper/stub execution remains experimental.
+- Paper/stub and reviewed test/sandbox validation execution remain
+  experimental and non-live.
 - Live broker adapters are not shipped in the initial core.
 - Raw broker secrets must not be stored in this repository or generated
   workspaces.
@@ -283,10 +278,11 @@ labels such as `research-only`, `screen-grade`, `not-decision-ready`, or
 
 ## Release Status
 
-`0.2.0` is the OrderTicket rewrite release for the generated workspace, Python
-CLI, Django service plane, product web, MCP boundary, and documentation set.
-The package still uses an alpha development classifier because live broker
-adapters and hosted service modes are intentionally outside the initial core.
+`0.2.1` is a compatibility patch on the `0.2.x` OrderTicket rewrite release
+line for the generated workspace, Python CLI, Django service plane, product
+web, MCP boundary, and documentation set. The package still uses an alpha
+development classifier because live broker adapters and hosted service modes
+are intentionally outside the initial core.
 
 ## Documentation
 

{tradingcodex-0.2.0 → tradingcodex-0.2.1}/docs/components.md

@@ -39,8 +39,12 @@ paths clear.
 | `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, handoff acceptance, artifact readiness, claim discipline, and synthesis gates. | `guardrail.guidance`, `improvement.workflow_quality` |
+| `artifact-quality-contract` | Evaluates workspace artifacts 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` |
+| `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` |
+| `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` |

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

@@ -10,7 +10,7 @@ not ship live broker execution.
 
 ## Release Policy
 
-The `0.2.0` release is the OrderTicket rewrite contract for the local-first
+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
@@ -26,8 +26,9 @@ Execution status for this release line:
 
 ## Maintainer Prerequisites
 
-Use Python 3.14 for release verification. The package metadata requires
-`>=3.14,<3.15`, and CI is pinned to Python 3.14.
+Use Python 3.11 for release build verification and keep CI green across the
+supported range. The package metadata requires `>=3.11,<3.15`, and CI runs on
+Python 3.11, 3.12, 3.13, and 3.14.
 
 Create separate PyPI and TestPyPI accounts. TestPyPI is a separate service and
 does not share login state with PyPI.
@@ -53,26 +54,26 @@ On GitHub, create both environments:
 Run the regular validation suite first:
 
 ```bash
-python3.14 -m pytest
-python3.14 manage.py check
-python3.14 manage.py makemigrations --check --dry-run
-python3.14 -m compileall tradingcodex_cli tradingcodex_service apps tests
+python3.11 -m pytest
+python3.11 manage.py check
+python3.11 manage.py makemigrations --check --dry-run
+python3.11 -m compileall tradingcodex_cli tradingcodex_service apps tests
 ```
 
 Build and check the source distribution and wheel:
 
 ```bash
-python3.14 -m pip install --upgrade build twine
+python3.11 -m pip install --upgrade build twine
 rm -rf dist build
 find . -maxdepth 1 -name '*.egg-info' -type d -exec rm -rf {} +
-python3.14 -m build
-python3.14 -m twine check dist/*
+python3.11 -m build
+python3.11 -m twine check dist/*
 ```
 
 Install the built wheel in a clean environment:
 
 ```bash
-python3.14 -m venv /tmp/tcx-install-test
+python3.11 -m venv /tmp/tcx-install-test
 /tmp/tcx-install-test/bin/pip install dist/*.whl
 rm -rf /tmp/tcx-smoke
 mkdir -p /tmp/tcx-smoke
@@ -135,11 +136,11 @@ Use TestPyPI before the first public PyPI release and after packaging changes.
 Example:
 
 ```bash
-python3.14 -m venv /tmp/tcx-testpypi
+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.0
+  tradingcodex==0.2.1
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -167,8 +168,8 @@ publication; tag pushes are intentionally non-publishing.
 After the PyPI workflow completes:
 
 ```bash
-python3.14 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.0
+python3.11 -m venv /tmp/tcx-pypi
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.1
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -207,7 +208,7 @@ TradingCodex has two update layers:
 including `workspace_id` and active profile. It may overwrite generated paths
 owned by `workspace_templates/modules/*/files`, and it must not overwrite
 workspace-native user artifacts such as `trading/research/*`,
-`trading/reports/*`, `.tradingcodex/strategies/*`, or optional role skills
+`trading/reports/*`, `.agents/skills/strategy-*`, or optional role skills
 except through their documented service-layer workflows.
 
 After a workspace update, users must fully quit and restart Codex, then start
@@ -220,7 +221,8 @@ Use PEP 440 versions:
 
 - `0.2.0` for the OrderTicket rewrite contract after install, docs, DB
   migration, generated workspace smoke checks, and release e2e checks are stable
-- patch releases such as `0.2.1` for compatible fixes after `0.2.0`
+- `0.2.1` for Python `>=3.11,<3.15` support and clone-free setup guidance
+- later patch releases for compatible fixes after `0.2.1`
 - pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
   the next minor contract
 

{tradingcodex-0.2.0 → tradingcodex-0.2.1}/docs/generated-workspaces.md

@@ -51,11 +51,20 @@ The target may be:
 Source checkouts of this repository are development projects, not generated
 TradingCodex workspaces.
 
-Codex agents must not silently create a default target when a user only asks to
+Codex agents must not run `git clone` when a user asks to install, set up,
+attach, or use `monarchjuno/tradingcodex` in a workspace. Run the packaged CLI
+from the target workspace instead:
+
+```bash
+uvx --refresh --from tradingcodex tcx attach . && ./tcx doctor
+```
+
+Agents must also not silently create a default target when a user only asks to
 install `monarchjuno/tradingcodex`. The agent rule is: do not invent a
-workspace path such as `tradingcodex-workspace`. If no target path is supplied,
-ask for the target directory before running the installer. If the user is
-already in an empty target workspace, install into `.`.
+workspace path such as `tradingcodex-workspace`. If no target path is supplied
+and the user did not ask to use the current workspace, ask for the target
+directory before running setup. If the user is already in an empty target
+workspace, install into `.`.
 
 ## Generated Files
 
@@ -94,13 +103,27 @@ Generated workspaces contain:
 - negated scope routing: phrases such as "no valuation", "no order", and "no trading" remove those actions or roles from dispatch selection
 - no full-history fixed-role spawn: fixed `agent_type` subagents receive compact assignment envelopes without full-history forking on the first attempt
 - subagent hook isolation: `UserPromptSubmit` auto-routing is ignored for fixed subagent contexts so subagent briefs cannot overwrite main-agent routing state or create recursive dispatch pressure
-- main-to-subagent briefs are assignment envelopes, not role manuals: they carry the current task, original request, explicit constraints, workflow consent posture, research artifact language, lane, artifact target, material context, request-specific out-of-scope items, and return contract without repeating long method/source/guardrail checklists
+- main-to-subagent briefs are assignment envelopes, not role manuals: they carry the current task, original request, explicit constraints, workflow consent posture, research artifact language, lane, artifact target, compact context summary, request-specific out-of-scope items, and return contract without repeating long method/source/guardrail checklists or pasting full artifacts
+- context-efficient research handoffs: stored markdown frontmatter includes
+  `context_summary` so downstream roles can consume artifact paths and summaries
+  before opening full markdown
+- context-budget audit: `./tcx subagents context-audit --strict` inspects the
+  latest prompt gate, prompt-gate history, compact hook context, subagent
+  session state, and research artifacts after long multi-subagent runs; it
+  fails strict mode when handoff artifacts lack `context_summary`, compact gate
+  history grows beyond budget, or gate/state/history payloads look like pasted
+  markdown artifacts
+- compact subagent session state: `.tradingcodex/mainagent/subagent-session-state.json`
+  keeps total counters plus recent active/completed/event records for Codex
+  context; the full event stream remains in
+  `trading/audit/subagent-session-events.jsonl`
 - fixed subagents configured for `model = "gpt-5.5"` and `model_reasoning_effort = "high"`
+- fixed subagent `nickname_candidates` set to a single item matching the exact role `name`
 - fixed subagent identities kept in `.codex/agents/*.toml` `developer_instructions`, as required by Codex custom agent files
 - project-local additional agent instructions under `.tradingcodex/agent-instructions/<role>.md`; projection appends them after generated default instructions for `head-manager` and fixed subagents
-- twenty-three core repo skills across project-scope mainagent skills and subagent skill directories, each with `SKILL.md` frontmatter for document metadata and `agents/openai.yaml` UI metadata
-- `strategy-*` skills under `.tradingcodex/strategies/*` for user-approved agent-readable investment strategies, created through `strategy-creator`, CLI, API, or service-layer flows and exposed to the root `head-manager` through the strategy marker block in `.codex/config.toml`; Django web lists and previews them read-only
-- file-native agent/skill projection: role skill state is expressed in `.codex/agents/*.toml`, `.agents/skills/*`, `.tradingcodex/subagents/skills/*`, `.tradingcodex/strategies/*`, `.codex/config.toml`, `.tradingcodex/mainagent/skill-change-proposals/*.yaml`, and `.tradingcodex/generated/*.json`, not Django skill DB tables
+- twenty-four core repo skills across project-scope mainagent skills and subagent skill directories, each with `SKILL.md` frontmatter for document metadata and `agents/openai.yaml` UI metadata
+- standalone `strategy-*` skills under `.agents/skills/strategy-*` for user-approved agent-readable investment strategies, created through `strategy-creator`, CLI, API, or service-layer flows and exposed to the root `head-manager` through the strategy marker block in `.codex/config.toml`; Django web lists and previews them read-only
+- file-native agent/skill projection: role skill state is expressed in `.codex/agents/*.toml`, `.agents/skills/*`, `.tradingcodex/subagents/skills/*`, `.codex/config.toml`, `.tradingcodex/mainagent/skill-change-proposals/*.yaml`, and `.tradingcodex/generated/*.json`, not Django skill DB tables
 - optional subagent skills are created, updated, activated, archived, deleted, and validated through the shared application service used by `head-manager`, CLI, API, and Django web
 - information-barrier policies
 - order/approval schemas
@@ -130,8 +153,7 @@ the operator wants to ask Codex agents to work.
 Recommended agent-facing flow:
 
 ```bash
-uv python install 3.14
-uv tool install --python 3.14 tradingcodex
+uv tool install tradingcodex
 uv tool update-shell
 cd <user-selected-workspace>
 tcx attach .
@@ -201,8 +223,13 @@ The package spec is recorded during bootstrap so PyPI and GitHub-source
 installs keep the same MCP source without stale source-cache reuse.
 
 Codex project config should register only the `tradingcodex` MCP server.
-Broker/data MCP servers are registered inside TradingCodex External MCP Gate
-with `./tcx mcp external ...`, not directly in `.codex/config.toml` or
+Broker APIs are attached through native TradingCodex connector profiles using
+canonical MCP tools such as `list_broker_connector_templates`,
+`register_broker_connector`, `get_broker_capability_profile`,
+`get_broker_instrument_constraints`, and `preview_order_translation`.
+Broker/data MCP servers, when explicitly needed for reviewed read-only
+discovery, are registered inside TradingCodex External MCP Gate with
+`./tcx mcp external ...`, not directly in `.codex/config.toml` or
 `.codex/agents/*.toml`.
 
 ## MCP Autostart
@@ -226,6 +253,32 @@ The autostart path must be:
 - silent on MCP stdout except for MCP protocol messages
 - not required for direct `./tcx mcp stdio` smoke checks
 
+Generated workspaces also support startup health for Codex sessions. The
+`SessionStart` hook writes a compact diagnostic cache at
+`.tradingcodex/mainagent/server-status.json`; it does not start services,
+update workspaces, or open browsers. `head-manager` then uses
+`$use-tradingcodex-server` to run service/MCP doctor checks, call
+`./tcx service ensure` when recovery is possible, and open the local dashboard
+in the Codex in-app browser when available before it offers a task menu or
+starts other work. If project MCP config was created or changed, the user must
+fully quit and restart Codex and start a new thread because Codex may not hot
+reload project MCP config.
+
+Startup health may also compare the generated workspace version in
+`.tradingcodex/generated/module-lock.json` with the currently installed/running
+`tcx` package version. The workspace version is the local baseline: if it
+differs from the installed `tcx` version, `head-manager` may recommend aligning
+the workspace to the installed version. If the installed `tcx` is known to be
+older than the latest TradingCodex release, workspace update is blocked until
+the package is updated first, so an old package does not refresh the workspace
+with stale templates. Update recommendations are scoped to the
+new-conversation health pass, not every user turn. If the user declines update
+prompts, `head-manager` records the TradingCodex home preference file, normally
+`~/.tradingcodex/preferences/update.json`, with
+`suppress_update_recommendation=true`; future new conversations should not
+recommend automatic workspace updates unless the user removes or changes that
+flag, or explicitly asks for an update.
+
 ## Hooks
 
 Generated hooks are Python scripts. Hook behavior is guidance, not final
@@ -238,6 +291,11 @@ enforcement.
 - natural-language investment workflow auto-routing context
 - direct-answer prevention context
 - duplicate marker management
+- prompt-gate audit metadata with prompt hash and workflow lane, without raw
+  prompt text in the audit ledger
+- compact hook `additionalContext`; the full generated starter prompt remains
+  in `.tradingcodex/mainagent/latest-user-prompt-gate.json` and is loaded only
+  when the compact gate is insufficient
 - execution negation routing such as "no order" and "no trading"
 - strategy authoring prompts remain in `strategy-creator`/strategy CRUD scope
   instead of auto-dispatching fixed investment subagents
@@ -245,6 +303,10 @@ enforcement.
   storage/read/rotation prompts create warning context without activating
   investment subagent dispatch unless a separate investment or execution
   request remains
+- startup server diagnostics: `SessionStart` records compact service and MCP
+  config status for `head-manager` to repair through `$use-tradingcodex-server`
+- update recommendation diagnostics: `SessionStart` records generated workspace
+  version drift and respects the TradingCodex home update preference file
 
 Hooks load only in trusted projects and may be disabled when
 `features.hooks=false`.

{tradingcodex-0.2.0 → tradingcodex-0.2.1}/docs/guardrails.md

@@ -73,6 +73,11 @@ Information barriers cover:
 - role-specific MCP allowlists
 - generated subagent permission profiles
 
+Information barriers are also a maintainability boundary. A new role or tool
+surface should update the barrier policy, role TOML, MCP allowlist, and tests
+together. Generic skills should not become the hidden place where file access,
+role eligibility, or tool authority is widened.
+
 The root `head-manager` may coordinate and inspect, but should not silently
 perform role work that belongs to specialist workflows.