tradingcodex 1.1.1__tar.gz → 1.2.0__tar.gz

{tradingcodex-1.1.1 → tradingcodex-1.2.0}/CHANGELOG.md

@@ -2,6 +2,115 @@
 
 ## Unreleased
 
+## 1.2.0 - 2026-07-20
+
+- Refresh the manual GitHub Pages workflow to the current Node 24 action
+  majors after the v1.1.2 candidate exposed the upstream Node 20 deprecation
+  annotation. The guide remains explicit-dispatch only.
+- Simplify Codex-native orchestration, hooks, and lifecycle boundaries while
+  retaining concise fixed-role prompts, direct native delegation, and
+  service-gated sensitive effects.
+- Keep root work on the user's active Codex model and reasoning settings while
+  fixed roles use `gpt-5.6-terra`/high, including explicit independent risk and
+  judgment review boundaries.
+- Preserve canonical research-artifact lookup when a supported export copies
+  Markdown between research and report paths. Current exports carry a
+  service-authenticated sidecar bound to central workspace provenance, while
+  pre-1.2 copies are recovered only when a retained signed receipt and, when
+  needed, a version archive prove the original path and bytes; altered,
+  replayed, copied-root, or ambiguous duplicates remain fail-closed.
+- Require the same central workspace provenance for every run-bound receipt
+  read, including compact review and card projections, so a copied workspace
+  cannot replay authenticated research with a shared local service key.
+- Keep optional OpenBB direct, add Snapshot/Dataset row-oriented reuse, and
+  strengthen conclusion-relevant point-in-time evidence, decision quality, and
+  artifact handoff guidance without adding provider or workflow services.
+- Add agent-maintained, Obsidian-compatible Knowledge Wikis with explicit write
+  admission, immutable community packages, bounded read-only Viewer search,
+  and a separate Brain-promotion boundary.
+- Record redacted external-tool observations for offline exact-repeat regression
+  checks; they do not infer outcome or block native tool use.
+
+## 1.1.2 - 2026-07-17
+
+- Add a cross-platform fixed-role calculation surface with generated
+  `tcx-calc`/`tcx-calc.cmd` launchers and a content-addressed runtime v2 outside
+  Django, MCP, the service home, DB, workspace, and scratch. Its wheel-only
+  per-artifact hash resource pins the complete 12-package direct/transitive
+  set around NumPy, pandas, SciPy, statsmodels, numpy-financial, and PyArrow.
+  The exact basename-only contract replaces host-dependent system
+  Python and heredocs, sanitizes environment and temp state before exposing the
+  verified runtime, rejects links and compound forms, applies resource bounds,
+  blocks child-process and network escape paths in prepared mode, verifies the
+  generated launcher hashes in doctor, and remains inside the native Codex OS
+  sandbox. Windows scratch now uses `TradingCodexScratch` so it cannot overlap
+  the default service home. Native Windows release smoke invokes both generated
+  batch launchers through tokenized `cmd /c call` commands so workspace paths
+  containing spaces retain their argument boundaries. Pinned packages may load
+  native libraries only from absolute paths inside the verified runtime and
+  only from an imported runtime-package frame; their process-local ctypes
+  bootstrap remains available, including CPython's exact Windows `kernel32`
+  import bootstrap. Scratch calls and external, other bare-name, or raw-integer-
+  handle loading remain denied. The explicit manual
+  release workflow gates the exact wheel through an x86-64 Linux/macOS/Windows
+  and Python 3.11-3.14 runtime matrix.
+- Separate ordinary GitHub uploads from deployment work. Normal source CI keeps
+  source, framework, and deterministic frontend checks but does not build or
+  upload distributions, run release-upgrade or platform matrices, or publish.
+  Documentation-only pushes and pull requests skip source CI, GitHub Pages
+  becomes manual-only, and package build/publication remains confined to
+  explicit Manual Release dispatches.
+- Add immutable Dataset memory with Source Snapshot lineage, explicit typed
+  manifests, content-addressed canonical Parquet payloads, append-only license
+  withdrawals, bounded card/manifest/profile/slice retrieval, and a managed
+  Git ignore rule for payload objects. A rebuildable SQLite+FTS v3 catalog now
+  unifies existing research artifacts with Dataset and Calculation objects,
+  reprojects only changed files, rebuilds after corruption, and continues the
+  legacy JSON exports for one compatibility release. Lineage timestamps cannot
+  predate their Source Snapshot or parent Dataset, withdrawn shared payloads
+  cannot be profiled, malformed manifests fail closed per object, and L0 cards
+  are size-bounded. Internally generated `Path` objects are normalized to the
+  portable forward-slash workspace form on native Windows while caller-supplied
+  backslash paths remain rejected.
+- Add prepared CalculationSpec/Run memory around `tcx-calc`, including declared
+  scratch inputs/outputs, typed finite result envelopes, exact full-fingerprint
+  reuse with a current-workflow reuse Run, comparison by requested metric, and
+  private-ledger snapshot hash binding without durable input values. The new
+  shared `tcx-calculation` skill gives the six financial calculation roles the
+  bounded procedure; Head Manager receives card-only planning discovery and
+  the viewer remains read-only. Calculation cards also project bounded symbols
+  and immutable Dataset relations so instrument-scoped role searches do not
+  miss an existing exact calculation. Prepared recording independently
+  revalidates script/input/sidecar/runtime/output hashes and schemas; Dataset
+  materializations and private central-ledger snapshots are service-bound
+  rather than caller-asserted.
+- Route legacy Source Snapshot, ResearchSpec, ReplayManifest, and ExperimentRun
+  path construction, regular-file reads, hash verification, and immutable
+  writes through the shared Research Object primitives while preserving their
+  released v1 hash encoding and IDs without migration.
+- Enable Head Manager live web search for narrow workflow-planning
+  reconnaissance. Durable root instructions and `tcx-workflow` keep raw search
+  results untrusted and prohibit using them as accepted evidence or synthesis
+  support; material facts must be reacquired by producing roles. Portfolio,
+  risk, and judgment-review roles explicitly keep web search disabled, and the
+  existing Build hook continues to block native web and browser tools.
+- Fix BYOR Codex capability use after the 1.1.1 gate removal. Head Manager and
+  fixed roles now distinguish explicit external skill overlays from read-only
+  app, connector, MCP, and data tools; inspect the current task's callable
+  surface before falling back or declaring a provider unavailable; and treat
+  the sanitized inventory as configuration evidence rather than runtime
+  callability proof. Capability inventory now names plugin app/MCP/hook
+  components from secret-free top-level identifiers and includes compatible
+  user skills discovered below `CODEX_HOME/skills`. Generated workspaces no
+  longer disable Codex apps, leaving app exposure to user, organization, and
+  host policy.
+- Align observed E2E behavior with the workspace contract: fixed roles may edit
+  files in their dedicated private scratch root while arbitrary external paths
+  remain blocked; viewer write-shaped requests consistently return GET-only
+  `405` responses even with CSRF enforcement; managed Brain and Strategy proof
+  errors name their own entrypoints; and E2E hooks execute through the generated
+  launcher runtime.
+
 ## 1.1.1 - 2026-07-16
 
 - Remove the legacy user-capability gate, its CLI and broker-import paths,

{tradingcodex-1.1.1 → tradingcodex-1.2.0}/MANIFEST.in

@@ -11,5 +11,7 @@ recursive-include frontend *.css *.html *.json *.js *.ts *.tsx
 recursive-include workspace_templates *
 recursive-include workspace_templates .*
 recursive-include tradingcodex_service/static *
+include tradingcodex_cli/calculation-runtime-lock.json
+include tradingcodex_cli/calculation-runtime-requirements.txt
 recursive-exclude frontend/node_modules *
 global-exclude *.py[cod]

{tradingcodex-1.1.1 → tradingcodex-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 1.1.1
+Version: 1.2.0
 Summary: Local-first investment operating system for Codex-native research and service-gated execution.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
@@ -29,13 +29,18 @@ Requires-Dist: markdown-it-py<5,>=3
 Requires-Dist: nh3<0.4,>=0.3
 Requires-Dist: packaging>=24
 Requires-Dist: pydantic>=2
+Requires-Dist: pyarrow==25.0.0
 Requires-Dist: PyYAML>=6
 Requires-Dist: whitenoise<7,>=6.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Dynamic: license-file
 
-# TradingCodex
+<h1 align="center">TradingCodex</h1>
+
+<p align="center">
+  <img src="assets/tradingcodex-banner-v3.png" alt="TradingCodex transforms fragmented investment tools into a native Codex research workflow" width="100%">
+</p>
 
 <div align="center">
   <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
@@ -54,7 +59,7 @@ next steps in your own workspace.
 It is not an autonomous trading bot. A research response never becomes a
 broker action on its own.
 
-[Get started](https://monarchjuno.github.io/tradingcodex/) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
+[Get started](https://monarchjuno.github.io/tradingcodex/) · [Data sources and OpenBB](docs/data-sources-and-openbb.md) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
 
 ## Start Here
 
@@ -101,7 +106,8 @@ need Node, npm, or a separate frontend server.
 | Review a past decision or validate a lesson | [`$tcx-memory`](https://monarchjuno.github.io/tradingcodex/skill-memory.html) | Replay from point-in-time evidence and distinguish decision quality from outcome quality. |
 | Create a reusable method or reasoning framework | [`$tcx-strategy`](https://monarchjuno.github.io/tradingcodex/skill-strategy.html) or [`$tcx-brain`](https://monarchjuno.github.io/tradingcodex/skill-brain.html) | Start directly with the matching skill in the normal Research profile; its current-turn scope cannot grant execution authority or cross into generic Build work. |
 | Monitor work on a schedule | [`$tcx-automate`](https://monarchjuno.github.io/tradingcodex/skill-automate.html) | Create or update a Codex Scheduled Task that invokes the actual work skill on each run. |
-| Open the dashboard or recover a workspace | [`$tcx-dashboard`](https://monarchjuno.github.io/tradingcodex/skill-dashboard.html) or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Open the read-only viewer inside Codex by default, request an external browser when needed, or receive a readiness check and safe recovery handoff. |
+| Open the viewer or recover a workspace | The Viewer and Wiki links shown when a healthy workspace task starts, or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Follow the read-only links directly; use the server skill for readiness checks and safe recovery guidance. |
+| Configure optional OpenBB data access | [Data sources](https://monarchjuno.github.io/tradingcodex/data-sources.html) | OpenBB is projected by default as a non-required direct MCP; use `tcx data-sources openbb status|disable|enable` to control it. It is never installed during attach. |
 | Connect a provider and prepare an order | [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) | Keep provider setup, account sync, ticket creation, checks, approval, and final action as separate checkpoints. |
 
 There are 13 user-facing skills. Browse their detailed behavior, examples, and
@@ -118,16 +124,16 @@ Analyze MSFT as a medium-term quality compounder. Separate facts, inferences,
 and assumptions. Include contrary evidence and invalidation conditions. No order.
 ```
 
-The workflow begins a lightweight, workspace-bound run. Head Manager selects
-only the fixed-role specialists the question needs, reassesses from accepted
-artifacts, and either synthesizes the result or states why work is waiting,
-needs revision, or is blocked.
+Narrow trusted questions can stay direct. Fresh research begins a lightweight,
+workspace-bound run; Head Manager selects only useful specialist profiles,
+uses bounded fallback when necessary, and reassesses from accepted evidence
+before answering, synthesizing, revising, or stopping on a gap.
 
 ## How TradingCodex Is Organized
 
 | Layer | What it does | What it does not do |
 | --- | --- | --- |
-| **Native Codex task** | Interprets the request, runs Head Manager, and dynamically dispatches exact fixed-role specialists. | It does not turn ordinary prose into an order or use a generic agent to imitate a specialist. |
+| **Native Codex task** | Interprets the request, takes a direct fast path when sufficient, and uses specialist profiles or a bounded generic child only when needed. | It does not turn ordinary prose, a child, or a skill into policy, approval, broker, or execution authority. |
 | **Workspace** | Holds readable research, reports, source snapshots, skills, prompts, and lightweight run provenance. | It is not the portfolio, order, account, approval, or secret ledger. |
 | **Django service** | Enforces artifact identity, policy, approval, broker, idempotency, execution, and audit rules through shared application services. | It does not replace Codex with a semantic router, preset team, or stored workflow DAG. |
 | **Read-only viewer** | Lets you browse Library artifacts, Skills, System posture, and registered workspaces. | It does not launch Codex, write workspace files, or mutate orders, brokers, skills, or policy. |
@@ -156,11 +162,11 @@ that state in prompts or workspace files.
 - Fixed roles have bounded tools and handoff responsibilities. A final order
   path is available only from an exact root-native protocol, never from the
   viewer, a subagent, public REST, generic CLI, or direct MCP call.
-- User-installed MCP servers, skills, and plugins are BYOR native Codex
-  capabilities. TradingCodex neither recommends nor verifies them; their
-  licenses, data terms, costs, and side effects remain the user/provider's
-  responsibility, and TradingCodex guarantees cover only its own capabilities,
-  state, and actions.
+- Relevant user-installed MCP servers and skills remain BYOR native Codex
+  capabilities. One relevant capability can be used for evidence without
+  becoming TradingCodex-managed. OpenBB is the one TradingCodex-supported
+  external data integration: it is optional, projected directly to evidence
+  roles, and still subject to upstream licenses and data terms.
 - Raw credentials do not belong in prompts, workspace files, reports, API/MCP
   output, or audit data.
 
@@ -175,6 +181,7 @@ guarantee returns.
 | [User Guide](https://monarchjuno.github.io/tradingcodex/) | Setup, examples, concepts, all user-facing skills, and provider-to-order onboarding. |
 | [Installation](installation.md) | Install variants, updates, runtime homes, MCP/service startup, and recovery. |
 | [User-facing skills](docs/user-facing-skills.md) | The full skill map, entry rules, and hard stops. |
+| [Data sources and OpenBB](docs/data-sources-and-openbb.md) | Source routing, direct optional OpenBB projection, Snapshot/Dataset evidence, and third-party terms. |
 | [Research memory and artifacts](docs/research-memory-and-artifacts.md) | Artifact paths, source posture, versions, quality labels, forecasts, and exports. |
 | [Decision memory](docs/decision-memory.md) | Replay, postmortems, lesson validation, and reusable context. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, brokers, secrets, and execution boundaries. |

{tradingcodex-1.1.1 → tradingcodex-1.2.0}/README.md

@@ -1,4 +1,8 @@
-# TradingCodex
+<h1 align="center">TradingCodex</h1>
+
+<p align="center">
+  <img src="assets/tradingcodex-banner-v3.png" alt="TradingCodex transforms fragmented investment tools into a native Codex research workflow" width="100%">
+</p>
 
 <div align="center">
   <a href="https://pypi.org/project/tradingcodex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/tradingcodex?label=PyPI"></a>
@@ -17,7 +21,7 @@ next steps in your own workspace.
 It is not an autonomous trading bot. A research response never becomes a
 broker action on its own.
 
-[Get started](https://monarchjuno.github.io/tradingcodex/) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
+[Get started](https://monarchjuno.github.io/tradingcodex/) · [Data sources and OpenBB](docs/data-sources-and-openbb.md) · [All user-facing skills](docs/user-facing-skills.md) · [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) · [Documentation](docs/README.md)
 
 ## Start Here
 
@@ -64,7 +68,8 @@ need Node, npm, or a separate frontend server.
 | Review a past decision or validate a lesson | [`$tcx-memory`](https://monarchjuno.github.io/tradingcodex/skill-memory.html) | Replay from point-in-time evidence and distinguish decision quality from outcome quality. |
 | Create a reusable method or reasoning framework | [`$tcx-strategy`](https://monarchjuno.github.io/tradingcodex/skill-strategy.html) or [`$tcx-brain`](https://monarchjuno.github.io/tradingcodex/skill-brain.html) | Start directly with the matching skill in the normal Research profile; its current-turn scope cannot grant execution authority or cross into generic Build work. |
 | Monitor work on a schedule | [`$tcx-automate`](https://monarchjuno.github.io/tradingcodex/skill-automate.html) | Create or update a Codex Scheduled Task that invokes the actual work skill on each run. |
-| Open the dashboard or recover a workspace | [`$tcx-dashboard`](https://monarchjuno.github.io/tradingcodex/skill-dashboard.html) or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Open the read-only viewer inside Codex by default, request an external browser when needed, or receive a readiness check and safe recovery handoff. |
+| Open the viewer or recover a workspace | The Viewer and Wiki links shown when a healthy workspace task starts, or [`$tcx-server`](https://monarchjuno.github.io/tradingcodex/skill-server.html) | Follow the read-only links directly; use the server skill for readiness checks and safe recovery guidance. |
+| Configure optional OpenBB data access | [Data sources](https://monarchjuno.github.io/tradingcodex/data-sources.html) | OpenBB is projected by default as a non-required direct MCP; use `tcx data-sources openbb status|disable|enable` to control it. It is never installed during attach. |
 | Connect a provider and prepare an order | [Provider to order](https://monarchjuno.github.io/tradingcodex/provider-to-order.html) | Keep provider setup, account sync, ticket creation, checks, approval, and final action as separate checkpoints. |
 
 There are 13 user-facing skills. Browse their detailed behavior, examples, and
@@ -81,16 +86,16 @@ Analyze MSFT as a medium-term quality compounder. Separate facts, inferences,
 and assumptions. Include contrary evidence and invalidation conditions. No order.
 ```
 
-The workflow begins a lightweight, workspace-bound run. Head Manager selects
-only the fixed-role specialists the question needs, reassesses from accepted
-artifacts, and either synthesizes the result or states why work is waiting,
-needs revision, or is blocked.
+Narrow trusted questions can stay direct. Fresh research begins a lightweight,
+workspace-bound run; Head Manager selects only useful specialist profiles,
+uses bounded fallback when necessary, and reassesses from accepted evidence
+before answering, synthesizing, revising, or stopping on a gap.
 
 ## How TradingCodex Is Organized
 
 | Layer | What it does | What it does not do |
 | --- | --- | --- |
-| **Native Codex task** | Interprets the request, runs Head Manager, and dynamically dispatches exact fixed-role specialists. | It does not turn ordinary prose into an order or use a generic agent to imitate a specialist. |
+| **Native Codex task** | Interprets the request, takes a direct fast path when sufficient, and uses specialist profiles or a bounded generic child only when needed. | It does not turn ordinary prose, a child, or a skill into policy, approval, broker, or execution authority. |
 | **Workspace** | Holds readable research, reports, source snapshots, skills, prompts, and lightweight run provenance. | It is not the portfolio, order, account, approval, or secret ledger. |
 | **Django service** | Enforces artifact identity, policy, approval, broker, idempotency, execution, and audit rules through shared application services. | It does not replace Codex with a semantic router, preset team, or stored workflow DAG. |
 | **Read-only viewer** | Lets you browse Library artifacts, Skills, System posture, and registered workspaces. | It does not launch Codex, write workspace files, or mutate orders, brokers, skills, or policy. |
@@ -119,11 +124,11 @@ that state in prompts or workspace files.
 - Fixed roles have bounded tools and handoff responsibilities. A final order
   path is available only from an exact root-native protocol, never from the
   viewer, a subagent, public REST, generic CLI, or direct MCP call.
-- User-installed MCP servers, skills, and plugins are BYOR native Codex
-  capabilities. TradingCodex neither recommends nor verifies them; their
-  licenses, data terms, costs, and side effects remain the user/provider's
-  responsibility, and TradingCodex guarantees cover only its own capabilities,
-  state, and actions.
+- Relevant user-installed MCP servers and skills remain BYOR native Codex
+  capabilities. One relevant capability can be used for evidence without
+  becoming TradingCodex-managed. OpenBB is the one TradingCodex-supported
+  external data integration: it is optional, projected directly to evidence
+  roles, and still subject to upstream licenses and data terms.
 - Raw credentials do not belong in prompts, workspace files, reports, API/MCP
   output, or audit data.
 
@@ -138,6 +143,7 @@ guarantee returns.
 | [User Guide](https://monarchjuno.github.io/tradingcodex/) | Setup, examples, concepts, all user-facing skills, and provider-to-order onboarding. |
 | [Installation](installation.md) | Install variants, updates, runtime homes, MCP/service startup, and recovery. |
 | [User-facing skills](docs/user-facing-skills.md) | The full skill map, entry rules, and hard stops. |
+| [Data sources and OpenBB](docs/data-sources-and-openbb.md) | Source routing, direct optional OpenBB projection, Snapshot/Dataset evidence, and third-party terms. |
 | [Research memory and artifacts](docs/research-memory-and-artifacts.md) | Artifact paths, source posture, versions, quality labels, forecasts, and exports. |
 | [Decision memory](docs/decision-memory.md) | Replay, postmortems, lesson validation, and reusable context. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, brokers, secrets, and execution boundaries. |

tradingcodex-1.2.0/docs/README.md

@@ -0,0 +1,101 @@
+# TradingCodex Documentation
+
+`docs/` is the canonical product reference. It explains durable behavior and
+the reasons behind it; it is not a second user guide or a source-file index.
+
+- New users start with the [User Guide](https://monarchjuno.github.io/tradingcodex/).
+- Operators start with [installation.md](../installation.md).
+- Maintainers start with [AGENTS.md](../AGENTS.md) and
+  [openwiki/quickstart.md](../openwiki/quickstart.md), then read the owning page
+  below before changing behavior.
+
+## Documentation Ownership
+
+| Layer | Purpose |
+| --- | --- |
+| `README.md` | Product summary and primary install route. |
+| `installation.md` | Setup, update, and operator recovery. |
+| `docs/` | Canonical product behavior, architecture, safety, and rationale. |
+| `guidebook/` | Short task-first instructions for end users. |
+| `openwiki/` | Source ownership and validation routing for coding agents. |
+| `AGENTS.md` | Repository-wide development rules. |
+
+Keep a concept in one owning document and link to it elsewhere. Update another
+layer only when its audience's route changes; do not copy a behavior contract
+into every layer. If two layers disagree, fix the owning `docs/` page first.
+
+## Start By Goal
+
+| Goal | Canonical page | Useful follow-up |
+| --- | --- | --- |
+| Understand the product and its design posture | [Product Direction](product-direction.md) | [Harness](harness.md) |
+| Understand runtime and source ownership | [System Architecture](system-architecture.md) | [Interfaces And Surfaces](interfaces-and-surfaces.md) |
+| Change Head Manager, roles, skills, or research flow | [Roles, Skills, And Workflows](roles-skills-and-workflows.md) | [Codex-Native Orchestration](codex-native-orchestration.md) |
+| Work with research evidence, datasets, and artifacts | [Research Memory And Artifacts](research-memory-and-artifacts.md) | [Data Sources And OpenBB](data-sources-and-openbb.md) |
+| Work with reusable company, product, technology, science, industry, or value-chain knowledge | [Knowledge Wikis](knowledge-wikis.md) | [Investment Brain Plugins](investment-brain-plugins.md) |
+| Understand saved decisions and improvement | [Decision Memory](decision-memory.md) | [Improvement Loop](improvement-loop.md) |
+| Change policy, approvals, brokers, or execution | [Safety, Policy, And Execution](safety-policy-and-execution.md) | [Guardrails](guardrails.md) |
+| Change attach/update or generated workspace files | [Generated Workspaces](generated-workspaces.md) | [Deployment](deployment.md) |
+| Change the viewer, API, MCP, Admin, or CLI | [Interfaces And Surfaces](interfaces-and-surfaces.md) | [System Architecture](system-architecture.md) |
+| Choose or verify validation | [Validation And Test Plan](validation-and-test-plan.md) | [Release Readiness](release-readiness.md) |
+
+## Reference By Domain
+
+### Product And Research
+
+- [Product Direction](product-direction.md) — product thesis, native-Codex
+  posture, goals, non-goals, defaults, and scope.
+- [Harness](harness.md) — how Codex, services, and workspace files cooperate.
+- [Financial Workflow References](financial-workflow-references.md) — finance
+  workflow evidence and non-expert output requirements.
+- [User-Facing Skills](user-facing-skills.md) — direct skill entrypoints and
+  user-visible responsibilities.
+- [Roles, Skills, And Workflows](roles-skills-and-workflows.md) — agent and
+  skill behavior, research routing, and handoffs.
+- [Codex-Native Orchestration](codex-native-orchestration.md) — the durable run
+  boundary and why Django is not an agent scheduler.
+- [Research Memory And Artifacts](research-memory-and-artifacts.md) — file-native
+  evidence, datasets, calculations, artifacts, and provenance.
+- [Knowledge Wikis](knowledge-wikis.md) — agent-maintained Obsidian-compatible
+  background knowledge, explicit write admission, community packages, and the
+  read-only Viewer.
+- [Data Sources And OpenBB](data-sources-and-openbb.md) — source fallback,
+  optional direct OpenBB MCP, and third-party terms.
+- [Decision Memory](decision-memory.md) and [Improvement Loop](improvement-loop.md)
+  — retained decisions, outcomes, lessons, and review.
+
+### Safety And Architecture
+
+- [Safety, Policy, And Execution](safety-policy-and-execution.md) — canonical
+  sensitive-action, approval, broker, secret, and audit boundary.
+- [Guardrails](guardrails.md) — guidance, enforcement, and information-barrier
+  taxonomy.
+- [System Architecture](system-architecture.md) — runtime planes, central DB,
+  app boundaries, and service ownership.
+- [Interfaces And Surfaces](interfaces-and-surfaces.md) — viewer, Admin, API,
+  MCP, CLI, and generated wrapper boundaries.
+- [Generated Workspaces](generated-workspaces.md) — attach/update, generated
+  files, projection, provenance, and platform rules.
+- [Investment Brain Plugins](investment-brain-plugins.md) — current managed
+  Brain behavior and migration context; native user skills remain the preferred
+  direction for future simplification.
+
+### Operations And Governance
+
+- [Validation And Test Plan](validation-and-test-plan.md) — complete validation
+  matrix; use the smallest relevant subset during iteration.
+- [Release Readiness](release-readiness.md) — release-specific evidence.
+- [Deployment](deployment.md) — packaging, publication, update, and CI policy.
+- [Licensing And Commercialization](licensing-and-commercialization.md) — open
+  source, generated workspace, trademark, and legal-review boundaries.
+
+## Writing Rules
+
+- Document durable behavior, not temporary implementation plans or completed
+  checklists; Git history preserves those.
+- Prefer links to repeated explanations. `openwiki/` should contain paths and
+  checks, not a second architecture narrative.
+- Keep user procedures in `guidebook/`; keep internal source paths out of it.
+- Keep product copy in English unless a reviewed localization layer is added.
+- A behavior change updates its owning page in the same change. A code-only
+  refactor that preserves behavior need not churn every documentation layer.

{tradingcodex-1.1.1 → tradingcodex-1.2.0}/docs/codex-native-orchestration.md

@@ -3,18 +3,18 @@
 Status: v1 contract
 
 TradingCodex uses Codex itself as the investment research orchestrator. Head
-Manager interprets the user's original language, chooses the smallest useful
-fixed-role team, runs independent work in parallel, waits for authenticated
-artifacts, and decides whether to revise, add a role, challenge a conflict,
-stop, or synthesize.
+Manager interprets the user's original language, answers narrow trusted facts
+directly, and uses the smallest useful role set when fresh research or distinct
+expertise is needed. It decides whether to follow up, add a role, challenge a
+conflict, stop, answer directly, or synthesize.
 
 ```text
 User
   -> Head Manager
      -> begin_analysis_run (identity, request hash, sealed Brain/Strategy/Context provenance)
      -> optional one explicit Investment Brain inquiry overlay
-     -> exact fixed-role children
-     -> authenticated research artifacts
+     -> optional role-profile or workflow-defined fallback children
+     -> optional authenticated research artifacts
      -> dynamic next-role judgment
      -> run-local synthesis artifact
 ```
@@ -45,6 +45,13 @@ validated plugin `brain_id`, version, content digest, source metadata, manifest
 and source paths, and projected skill path. It does not store the raw request,
 a selected team, a plan, or a task queue.
 
+Codex owns thread, child, wait, and follow-up lifecycle. TradingCodex does not
+pre-allocate or mirror a Codex session-to-run map. When durable research
+provenance is needed, `begin_analysis_run` creates the run ID and Head Manager
+passes that returned ID in compact child briefs and authenticated artifact
+calls. A follow-up in the same Codex task reuses that ID from task context;
+TradingCodex does not reconstruct it from a session map.
+
 ## Investment Brain Context
 
 The native task may select at most one Primary Brain through one exact
@@ -72,23 +79,30 @@ falsify a Brain or Strategy assumption. Strategy governs a decision-rule
 conflict with Brain, while Investor Context remains blocking when suitability
 conflicts with Strategy.
 
-## Dispatch Contract
-
-Every fixed-role child uses MultiAgent V2 with:
-
-- explicit `features.multi_agent_v2.enabled = true`
-- seven total session threads, preserving six child slots before the
-  TradingCodex reserved-slot policy
-- exact registered `agent_type`
-- compact underscore-only `task_name`
-- compact role-owned assignment containing the analysis run id
-- `fork_turns="none"`
-- the role's projected model, reasoning effort, sandbox, web posture, skills,
-  and MCP principal
-
-Each revision or follow-up is a fresh child. `followup_task`, generic/default
-agent fallback, full-history fork, role-TOML emulation, and source-code routing
-are not valid TradingCodex paths.
+## Delegation Contract
+
+MultiAgent V2 exposes the generated role profiles with a depth-one boundary.
+Head Manager prefers an exact profile when its specialty is useful and passes a
+compact role-owned brief rather than the full root history. Role TOML supplies
+the direct fixed model settings; their values and fallback eligibility are owned
+by [Roles, Skills, And Workflows](roles-skills-and-workflows.md). Role profiles
+retain their projected web posture, skills, tools, and MCP principal.
+
+For an exact profile, Head Manager calls native `spawn_agent` with the exact
+`agent_type`, a compact `message`, a `task_name`, and `fork_turns="none"`. It
+does not pass `model` or `reasoning_effort`. A spawn is real only when the tool
+returns a live target. Correct a rejected spawn only when its error identifies
+the change; otherwise delegation remains blocked.
+
+Use `followup_task` when a live child still owns a correction or clarification.
+Start another child for a new specialty, an unavailable session, or independent
+review. Apply the canonical fallback boundary in
+[Roles, Skills, And Workflows](roles-skills-and-workflows.md). A child cannot
+approve, execute, access a broker, or emulate Head Manager. Children never
+delegate recursively. Head Manager waits only while a live child has useful work
+and reports lifecycle events only from native tool and child-lifecycle results
+in the current run. Native wait is wait-any and may serialize with no explicit
+target list; that representation is not failure by itself.
 
 When a Brain applies, the assignment contains the question Head Manager derived
 from it, not the Brain body or a delegation of Brain authority. Brain content is
@@ -96,7 +110,8 @@ never copied into fixed-role configuration.
 
 ## Artifact And Lineage Contract
 
-Producing roles store their own output through `create_research_artifact`.
+Decision-, reuse-, audit-, or handoff-relevant roles store their own output
+through `create_research_artifact`; a narrow bounded answer need not create one.
 Authenticated service code derives the producer identity and content hash,
 verifies the analysis run, and resolves exact run-local `input_artifact_ids`
 into immutable input hashes. Head Manager reads exact returned artifact IDs
@@ -147,14 +162,20 @@ Brain invocation occur in native Codex tasks.
 
 A passing native smoke proves:
 
-1. hooks provide transport/run context without semantic classification;
-2. Head Manager calls `begin_analysis_run` for a fresh investment request;
+1. hooks provide compact context and proof gates without semantic classification
+   or generic shell-policy duplication;
+2. Head Manager uses the direct fast path or calls `begin_analysis_run` only for
+   fresh research and decision work;
 3. Korean and English requests both route by agent understanding;
-4. exact Sol Head Manager and Terra roles use the configured reasoning levels;
-5. spawns use exact V2 role identity and `fork_turns="none"`;
-6. no Brain preserves baseline behavior, one exact Brain changes only inquiry
+4. generated root TOML inherits the user's model and reasoning settings, while
+   fixed-role TOML applies the child settings defined by the canonical role
+   contract;
+5. exact profiles spawn with compact fresh context, child follow-up targets a
+   returned live child, and lifecycle claims match completed native tool calls;
+6. fallback behavior matches the canonical role contract;
+7. no Brain preserves baseline behavior, one exact Brain changes only inquiry
    and interpretation, and multiple or unresolved Brains fail closed;
-7. artifacts are principal-bound and preserve run-local Brain and input lineage;
-8. Head Manager dynamically revises from artifacts without old plan tools;
-9. memory-influenced judgment is blind-first and reports its delta; and
-10. order/approval/execution gates remain service-owned.
+8. artifacts are principal-bound and preserve run-local Brain and input lineage;
+9. Head Manager dynamically revises from artifacts without old plan tools;
+10. memory-influenced judgment is blind-first and reports its delta; and
+11. order/approval/execution gates remain service-owned.