tradingcodex 1.2.1__tar.gz → 2.1.0__tar.gz

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## 2.1.0 - 2026-07-23
+
+- Ship the complete compact Artifact v2, receipt v4, canonical synthesis,
+  JudgmentSnapshot/User Adoption, and Decision Episode vertical slice across
+  CLI, MCP, REST, generated workspaces, and the read-only Viewer.
+- Make outcome-blind process review ordering enforceable, bind JudgmentSnapshot
+  Forecast posture to the authenticated synthesis, and retain durable blocked
+  abstentions without granting action authority.
+- Fail closed on unauthenticated run-bound cards and Episode lineage, expose
+  locked process reviews and bounded lifecycle records in Episodes, reject
+  unknown nested REST envelope fields, and document the explicit v1-to-v2
+  workspace transition.
+
+## 2.0.0 - 2026-07-23
+
+- Replace the public research-artifact write and read contracts with compact v2
+  envelopes, two-axis readiness, receipt v4 provenance, and one canonical Head
+  Manager synthesis identity per analysis run while preserving authenticated v1
+  files and receipts byte-for-byte through an explicit v1-to-v2 update path.
+- Add evidence-only JudgmentSnapshots, explicit terminal-recorded User Adoption
+  events, judgment-bound postmortems, and read-only Decision Episode projections
+  across MCP, API, CLI, and the workspace Viewer.
+- Make final Head Manager answers self-contained and decision-focused; durable
+  reports retain full provenance and are linked as supporting records instead of
+  being restated as a table of contents in chat.
+
+## 1.2.2 - 2026-07-22
+
+- Validate Codex CLI 0.145.0 as the current reference while retaining 0.144.4
+  as the compatibility floor; adopt its stable MultiAgent V2 schema by leaving
+  nesting and concurrency to native Codex while preserving strict config,
+  permission, hook, MCP, and role-model projection checks.
+- Restore the Head Manager's generated `export_dataset_csv` projection by
+  registering its canonical MCP schema, role boundary, and export capability,
+  with a generated-config-to-registry regression check.
+- Stop automated GitHub Release notes at the next changelog heading so a
+  release contains only its matching version section.
+
 ## 1.2.1 - 2026-07-21
 
 - Create or refresh the GitHub Release from the exact verified distributions

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 1.2.1
+Version: 2.1.0
 Summary: Local-first investment operating system for Codex-native research and service-gated execution.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/docs/README.md

@@ -5,9 +5,9 @@ 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.
+- Maintainers start with [AGENTS.md](../AGENTS.md) and the codebase
+  [Architecture](architecture.md), then read the owning page below before
+  changing behavior.
 
 ## Documentation Ownership
 
@@ -17,7 +17,6 @@ the reasons behind it; it is not a second user guide or a source-file index.
 | `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
@@ -29,14 +28,14 @@ into every layer. If two layers disagree, fix the owning `docs/` page first.
 | 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) |
+| Understand runtime and source ownership | [Architecture](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) |
+| Change the viewer, API, MCP, Admin, or CLI | [Interfaces And Surfaces](interfaces-and-surfaces.md) | [Architecture](architecture.md) |
 | Choose or verify validation | [Validation And Test Plan](validation-and-test-plan.md) | [Release Readiness](release-readiness.md) |
 
 ## Reference By Domain
@@ -70,8 +69,8 @@ into every layer. If two layers disagree, fix the owning `docs/` page first.
   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.
+- [Architecture](architecture.md) — codebase map, consequential request flow,
+  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
@@ -94,8 +93,9 @@ into every layer. If two layers disagree, fix the owning `docs/` page first.
 
 - 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.
+- Prefer links to repeated explanations. Keep the codebase map in
+  `architecture.md` and validation routing in `AGENTS.md`, not in parallel
+  documentation layers.
 - 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

tradingcodex-1.2.1/docs/system-architecture.md → tradingcodex-2.1.0/docs/architecture.md

@@ -1,7 +1,10 @@
-# System Architecture
+# TradingCodex Architecture
 
-This document owns TradingCodex architecture, Django app boundaries, central DB
-ownership, service-layer use cases, runtime planes, and core model ownership.
+This document is the codebase map and canonical architecture reference for
+TradingCodex. It owns runtime and dependency boundaries, source and state
+ownership, Django app boundaries, central DB ownership, service-layer use
+cases, and core model ownership. Repository-wide development constraints and
+the minimum validation route remain in [`AGENTS.md`](../AGENTS.md).
 
 ## Architecture Summary
 
@@ -31,43 +34,82 @@ optional role skills, and `strategy-*` skills are managed user overlays. The
 harness coordinates those layers; it is not the product definition and an
 overlay never replaces the kernel.
 
-## Source Tree
+## Model-Aware Consequence Flow
+
+The Codex agent changing this repository and agents running inside a
+TradingCodex workspace may use the same GPT/Codex model family. The
+implementing agent's own likely interpretation and behavior are therefore a
+useful design signal, especially when reviewing prompts, skills, tool exposure,
+and delegation. They are not proof of identical runtime behavior: system
+instructions, context, enabled capabilities, permissions, model versions, and
+reasoning settings may differ.
+
+Trace consequential behavior end to end before adding or changing harness
+machinery:
+
+```text
+user request
+  -> model interpretation and chosen response path
+  -> prompt, skill, and available-context guidance
+  -> tool or subagent selection
+  -> TradingCodex interface and application-service boundary
+  -> workspace artifact, durable record, or external action
+  -> safety, audit, latency, context, and user-visible consequences
+```
+
+Fix behavior at the earliest canonical layer that causes it. Do not add a
+router, validator, retry loop, registry, or state machine merely to compensate
+for behavior native Codex already handles or that clearer context and guidance
+can resolve. For consequential prompt, skill, tool, or orchestration changes,
+observe the actual generated TradingCodex harness; unit tests and assumptions
+about the model cover deterministic contracts but do not replace runtime
+evidence.
+
+## Codebase Map
+
+Use this map to find the canonical owner, then inspect that owner, its callers,
+and focused tests. It intentionally lists stable directories and entrypoints
+rather than every file.
+
+| Path | Ownership |
+| --- | --- |
+| `tradingcodex_service/application/` | Canonical durable use cases, state transitions, provenance, projections, and sensitive-action gates. |
+| `apps/*/models.py`, `apps/*/admin.py` | Central Django ledger models, migrations, and local Admin inspection. Thin `services.py` modules re-export canonical application services where required. |
+| `tradingcodex_service/api.py`, `viewer_api.py`, `web.py` | Local API and read-only web surfaces; these call application services and own no parallel business logic. |
+| `tradingcodex_service/mcp_runtime.py` | TradingCodex MCP definitions, role visibility, validation, and dispatch into application services. |
+| `tradingcodex_cli/` | Attach/update, generated-workspace lifecycle, operator commands, service startup, and the isolated calculation runner. |
+| `workspace_templates/modules/*/files/` | Source templates for projected prompts, skills, agents, hooks, policies, launchers, and workspace contracts. Generated copies are not edited directly. |
+| `frontend/` | Maintainer-only React/TypeScript viewer source. |
+| `tradingcodex_service/static/tradingcodex_web/` | Deterministic generated frontend build served by Django; never hand-edited. |
+| `tests/` | Unit, contract, safety, generated-workspace, platform, and native Codex validation. |
+| `docs/` | Canonical product behavior, architecture, safety, workflow, validation, and release rationale. |
+| `guidebook/` | Concise, task-first user instructions. |
+| `README.md`, `installation.md`, `install.sh` | Product entrypoint, installation contract, and source-development bootstrap. |
+
+### Domain Owners
+
+| Concern | Primary source |
+| --- | --- |
+| Runtime home, workspace identity, and service lifecycle | `tradingcodex_service/application/runtime.py`, `workspaces.py`, `health.py`; `tradingcodex_cli/generator.py`, `startup_status.py` |
+| Agent roles, skills, analysis runs, and harness display | `tradingcodex_service/application/agents.py`, `analysis_runs.py`, `harness.py`; `workspace_templates/modules/` |
+| File-native research, datasets, calculations, and provenance | `tradingcodex_service/application/artifact_v2.py`, `research.py`, `research_objects.py`, `datasets.py`, `calculations.py`, `artifact_bindings.py`, `artifact_catalog.py` |
+| Judgments, adoption, forecasts, postmortems, and episode projection | `tradingcodex_service/application/judgments.py`, `decision_episodes.py`, `judgment_postmortems.py`, `forecasting.py`; `decision_packages.py` and `postmortems.py` remain legacy read paths |
+| Knowledge Wikis and managed packages | `tradingcodex_service/application/knowledge_wikis.py`, `managed_package_sources.py`, `wiki_viewer.py` |
+| Policy, orders, approvals, brokers, and final execution | `tradingcodex_service/application/policy.py`, `orders.py`, `execution_gateway.py`, `brokers.py`, plus the corresponding `apps/` models |
+| Viewer, API, Admin, CLI, and MCP surfaces | Interface entrypoints above; all durable behavior remains in `application/` |
+| Generated workspace projection | `tradingcodex_cli/generator.py`, module manifests, and `workspace_templates/modules/*/files/` |
+
+## Conceptual Source Tree
 
 ```text
+README.md / installation.md / install.sh
 pyproject.toml
 manage.py
 frontend/
-  package.json
   src/
-  vite.config.ts
 tradingcodex_service/
-  static/tradingcodex_web/
   application/
-    brokers.py
-    build_gateway.py
-    common.py
-    execution_gateway.py
-    runtime.py
-    orders.py
-    portfolio.py
-    policy.py
-    research.py
-    research_objects.py
-    research_object_catalog.py
-    datasets.py
-    calculations.py
-    research_specs.py
-    investment_analysis.py
-    forecasting.py
-    evaluation_lab.py
-    audit.py
-    harness.py
-    analysis_runs.py
-    investment_brains.py
-    viewer.py
-    workspace_git.py
-    workspaces.py
-    health.py
+  static/tradingcodex_web/  # generated frontend build
 tradingcodex_cli/
   commands/
 apps/
@@ -78,16 +120,16 @@ apps/
   orders/
   policy/
   portfolio/
-  research/
-  workflows/
 workspace_templates/
+  modules/
 tests/
 docs/
+guidebook/
 ```
 
 The source tree above is conceptual. Large service modules may be refactored
 into packages under `tradingcodex_service/application/` when that improves
-maintainability. For the v1 release contract, implementation should split by
+maintainability. For the current release contract, implementation should split by
 durable service use case rather than by interface surface. Web, API, CLI, MCP,
 and generated hooks should continue calling the
 same application services instead of growing separate policy, execution,
@@ -102,7 +144,7 @@ update` never run npm.
 
 Durable service implementation lives under
 `tradingcodex_service/application/`. CLI command implementations live under
-`tradingcodex_cli/commands/`. The v1 codebase uses these canonical modules
+`tradingcodex_cli/commands/`. The codebase uses these canonical modules
 directly.
 
 ## Runtime Planes
@@ -280,11 +322,15 @@ refuses remote hosts or an unverified listener PID.
 | `policy` | Principals, capabilities, restricted list, limits, policy decisions. |
 | `orders` | Canonical order tickets, order checks, approval receipts, current-turn order grants, broker order timeline, fills, and execution attempts/results. |
 | `portfolio` | Cash, positions, exposure snapshots, normalized ledger events, broker sync runs, reconciliation runs, paper portfolio state. |
-| `research` | Workspace markdown research artifacts, artifact versions, evidence packs, report metadata, file-native source/as-of snapshots, immutable Dataset and Calculation objects, and rebuildable catalog projections. No Django DB models or Admin DB surface. |
 | `audit` | Append-only audit events, request hashes, result hashes, policy/action provenance. |
 | `mcp` | Protocol adapter metadata, tool registry, and non-research tool call ledger. |
 | `integrations` | Broker connections, broker accounts, instrument maps, paper and validation-only execution paths, read-only data adapters, future broker adapter definitions. |
 
+File-native research has no Django app, DB models, or Admin DB surface.
+Workspace markdown artifacts, versions, evidence packs, source/as-of snapshots,
+immutable Dataset and Calculation objects, and rebuildable catalog projections
+are owned by `tradingcodex_service/application/` services.
+
 ## Service Layer Rules
 
 Interfaces must call shared service functions rather than duplicating durable
@@ -394,18 +440,26 @@ Read/write research and audit use cases:
 - `get_forecast`
 - `list_forecasts`
 - `calibration_report`
+- `record_judgment_snapshot`
+- `get_judgment_snapshot`
+- `list_judgment_snapshots`
+- `record_decision_adoption`
+- `record_judgment_process_review`
+- `create_judgment_postmortem`
+- `list_decision_episodes`
+- `get_decision_episode`
 - `create_evaluation_corpus`
 - `record_evaluation_run`
 - `record_blind_human_review`
 - `compare_evaluation_runs`
 - `record_audit_event`
 
-Research artifact writes preserve workspace markdown as the source of truth and
-carry handoff metadata for source/as-of posture, clear distinctions among facts,
-analysis, and assumptions, confidence, missing evidence, next-recipient routing, blocked actions, and
-source snapshots. `quality-check --strict` validates the markdown handoff
-contract, Evidence Run Card shape, and Validation Card shape without moving
-research memory into the central DB.
+Research artifact writes preserve workspace markdown as the source of truth.
+V2 stores a compact identity, status, summary, requirement, and lineage
+envelope in Markdown; receipt v4 seals the exact versions, hashes, and run
+context omitted from that reader-facing file. `quality-check --strict`
+validates the markdown handoff contract, Evidence Run Card shape, and
+Validation Card shape without moving research memory into the central DB.
 
 Dataset manifests and Calculation specs/runs use the same immutable research-
 object primitives as Source Snapshots, ResearchSpecs, and ExperimentRuns.
@@ -462,6 +516,13 @@ producer, exact inputs, and Brain/Strategy/Investor Context lineage. Synthesis,
 forecasts, and Decision Memory reverify receipts instead of trusting Markdown
 frontmatter or caller-supplied lineage.
 
+The Decision Episode viewer is a read projection, not another workflow state
+store. It joins the run, authenticated synthesis and role artifacts, forecasts,
+JudgmentSnapshot, explicit User Adoption, process review/Postmortem, and lesson
+status by `workflow_run_id`. Each lifecycle dimension remains independently
+projected, and ambiguous legacy synthesis candidates are surfaced rather than
+chosen by the viewer.
+
 The viewer adds no run state beside the lightweight native run under
 `.tradingcodex/mainagent/runs/<analysis-run-id>/` and launches no Codex process.
 It reads canonical activity and accepted artifacts through the shared service

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/docs/codex-native-orchestration.md

@@ -1,6 +1,6 @@
 # Codex-Native Orchestration
 
-Status: v1 contract
+Status: current contract
 
 TradingCodex uses Codex itself as the investment research orchestrator. Head
 Manager interprets the user's original language, answers narrow trusted facts
@@ -81,7 +81,8 @@ conflicts with Strategy.
 
 ## Delegation Contract
 
-MultiAgent V2 exposes the generated role profiles with a depth-one boundary.
+MultiAgent V2 exposes the generated role profiles through native Codex
+delegation.
 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
@@ -98,11 +99,15 @@ 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.
+approve, execute, access a broker, or emulate Head Manager. Whether to delegate
+a distinct child-owned subtask further is a native Codex decision, not a
+TradingCodex workflow requirement. Every descendant remains subject to its
+selected projected role and the shared evidence, authority, and safety
+boundaries. 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

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/docs/data-sources-and-openbb.md

@@ -34,11 +34,34 @@ attempted before that fallback unless the user selected another provider.
 Evidence is fit to a claim and intended use rather than accepted or rejected by
 provider class. Original public records remain preferred when a claim requires
 source-of-record authority, but attributable non-primary evidence may support
-the fields and periods it actually covers. Missing or ambiguous coverage limits
-only dependent claims and actions; it does not erase independent valid fields
-or prevent factual and screen-grade research. This preserves the distinction
-between evidence usability and decision or execution readiness without adding
-a provider trust score, allowlist, or routing registry.
+the fields and periods it actually covers. OpenBB is an access layer, not a
+source class: judge a result by its returned provider, identifiers, periods,
+units, adjustments, freshness, and coverage. Current attributable data from a
+credible OpenBB provider is usable on the same terms as data retrieved from
+that provider directly.
+
+Use source-of-record evidence when exact legal, regulatory, contractual,
+accounting, filing, or official-policy status is itself material. For market
+prices, normalized fundamentals, estimates, industry developments, event
+chronology, and interpretation, a credible institutional provider or reputable
+secondary publication may support a conclusion when it is attributable,
+current for the claim, within the source's competence, and free of unresolved
+material conflict. Secondary does not mean screen-only. Corroborate in
+proportion to consequence: independently check a conclusion-driving claim when
+it is surprising, disputed, transformed from raw data, or weakly attributed;
+do not impose a fixed source count on ordinary well-supported facts.
+
+Missing or ambiguous coverage limits only dependent claims and actions; it
+does not erase independent valid fields or automatically downgrade the whole
+artifact. `decision-grade` evidence may use a mixture of official records,
+OpenBB/provider data, and reputable secondary evidence when every
+conclusion-driving claim has fit-for-purpose support, a current market anchor
+exists when relevant, and material conflicts and gaps are explicit.
+`screen` evidence readiness is for a gap that materially prevents responsible decision
+support, not for the mere absence of a primary source. Confidence records the
+strength and independence of support separately from readiness. This preserves
+evidence usability and decision readiness without adding a provider trust
+score, allowlist, or routing registry.
 
 Freshness is relative to the requested as-of, the source's observation or
 publication cadence, the relevant instrument or venue session, and the claim.

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/docs/decision-memory.md

@@ -34,13 +34,13 @@ tools, persistence, memory, policy, approval, broker, order, or execution.
 ## Canonical Architecture
 
 ```text
-raw source snapshots
+Research Artifacts
         |
-immutable ResearchSpec + replay manifest
+point-in-time Synthesis
         |
-frozen decision package + forecast events
+Judgment Snapshot + optional User Adoption
         |
-separately observed outcome + proper score
+Forecast outcome + proper score
         |
 two-pass postmortem
         |
@@ -61,8 +61,9 @@ The source of truth is the existing file-native record:
 - immutable ResearchSpecs and replay manifests;
 - experiment runs that bind code, data, config, model, prompt, tool, and trial
   provenance;
-- planned Decision Packages, immutable accepted decision snapshots, and
-  accepted role artifacts;
+- accepted role artifacts and canonical synthesis, immutable JudgmentSnapshots,
+  explicit User Adoption events, and legacy DecisionSnapshots retained
+  read-only;
 - append-only forecast issue, revision, resolution, dispute, and score events;
 - audit-backed postmortems and append-only improve records; and
 - Investment Brain id/version/content digest, Strategy hash, and Investor
@@ -71,7 +72,7 @@ The source of truth is the existing file-native record:
 Existing events are not edited to make history look cleaner. Corrections,
 revisions, supersession, disputes, and retirement are new records.
 
-The rebuildable v2 artifact catalog provides a discovery projection across
+The rebuildable v3 artifact catalog provides a discovery projection across
 these file-native records without becoming Decision Memory itself. New
 type-specific service output projects with full canonical identity metadata;
 older files remain unchanged and may project as `legacy_partial`. Malformed
@@ -260,16 +261,43 @@ selection bias.
 A good process can have a bad outcome, and a poor process can have a profitable
 outcome. Outcome knowledge must not rewrite what was reasonably knowable.
 
-The skill seals accepted decision-time state with `./tcx decision snapshot
-record`, locks the outcome-blind first pass with `./tcx postmortem
-process-review`, and only then creates the outcome-attached report with `./tcx
-postmortem create`. These commands accept a JSON payload file or `-` for stdin;
-they validate recorded workflow, artifact, forecast, strategy, and
-investor-context hashes instead of trusting free-form Markdown. Lesson
+Head Manager autonomously seals an evaluable accepted synthesis with the
+role-scoped `record_judgment_snapshot` MCP tool. Factual and screening synthesis
+is not frozen. A durable `insufficient` abstention may still be frozen when its
+future process or outcome is worth evaluating; it remains action-blocked. The
+snapshot binds the canonical synthesis receipt, analysis run context, cutoff,
+and Forecast refs or the canonical reason Forecast was inapplicable. Caller
+input cannot contradict the synthesis Forecast posture. It has
+`authority: evidence_only` and creates no execution permission.
+
+User Adoption is separate. TradingCodex never infers it from conversation,
+viewer activity, a recommendation, or order preparation. The user explicitly
+records an immutable event with `./tcx decision adopt <payload.json|->`; it
+binds the Judgment hash and user's decision statement and may supersede an
+earlier Adoption. Adoption still is not order approval or execution authority.
+
+Postmortem locks the outcome-blind first pass with `./tcx postmortem
+process-review`, then creates the outcome-attached report with `./tcx
+postmortem create`. Process quality can be assessed against Judgment alone;
+claims about what the user actually decided require an Adoption ref. Lesson
 promotion has no direct or generic CLI path: an authenticated
 `judgment-reviewer` performs it through the role-scoped `promote_lesson` MCP
 tool.
 
+### Decision Episode projection
+
+`Decision Episode` is a read model, not stored workflow state. It groups by
+`workflow_run_id`: run record, verified synthesis and role artifacts, Forecast
+events, JudgmentSnapshot, User Adoption, process review/Postmortem, and Lesson
+status. Analysis, judgment, adoption, forecast, postmortem, and lesson keep
+separate statuses; there is no lifecycle enum that falsely implies a single
+linear state machine. Legacy runs with one synthesis use it; multiple legacy
+synthesis candidates produce `ambiguous_legacy_synthesis` and are never
+resolved by guessing. Public cards, search, Library, and Episode projections
+verify every run-bound artifact receipt before displaying its fields or using
+its Dataset and Calculation lineage. The Episode exposes a locked process
+review independently from a completed Postmortem.
+
 ### Separate error loops
 
 Do not combine every failure into one Error Book:

{tradingcodex-1.2.1 → tradingcodex-2.1.0}/docs/deployment.md

@@ -8,18 +8,24 @@ templates, Django Admin, MCP gateway, and the committed React viewer build.
 Django and WhiteNoise serve the viewer. End users and generated workspaces
 do not need Node or npm.
 
-## v1 Release Contract
+## v2 Release Contract
 
-`1.0.0` is the first supported public contract for the current Web, Admin, API,
-CLI, MCP, generated workspace, application-service, policy, approval, audit,
-and execution boundaries.
+`2.0.0` introduced the breaking public contract for compact Artifact v2,
+receipt v4,
+JudgmentSnapshot/User Adoption, and Decision Episode reads across Web, API,
+CLI, MCP, and application services. Existing authenticated v1 Markdown,
+version archives, and receipts remain byte-preserved and readable through the
+v2 projection; all new artifact writes use v2. `2.1.0` is the first hardened
+minor release of that contract, adding fail-closed public projections,
+outcome-blind ordering enforcement, and complete Episode lifecycle detail.
 
-The v1 baseline is intentionally clean:
+The release baseline is intentionally clean:
 
 - new installations attach an empty workspace with `tcx attach`
-- v1 workspaces update through the documented v1 package and workspace flow
-- generated files, runtime state, and database schema use the v1 contract
-- historical prerelease compatibility surfaces are not part of the v1 runtime
+- v1 workspaces upgrade only through the explicit documented v1-to-v2 update
+  path; other major-version mismatches fail closed
+- generated files, runtime state, and database schema use the v2 contract
+- old public artifact request fields are rejected rather than accepted as aliases
 - paper execution is built in; live execution remains disabled by default and
   requires an installed provider plus every policy, approval, idempotency,
   connection, confirmation, sync, and audit gate
@@ -28,7 +34,7 @@ If the selected runtime database contains prerelease migrations or project
 tables without clean v1 migration history, startup and bootstrap fail closed.
 The error reports the selected `TRADINGCODEX_HOME` and database path.
 TradingCodex does not migrate, delete, archive, or back up incompatible
-prerelease/non-v1 state.
+prerelease state.
 
 The operator must choose one explicit recovery path:
 
@@ -38,7 +44,7 @@ The operator must choose one explicit recovery path:
 2. Stop every TradingCodex process, then archive or remove the old selected
    home/database manually before retrying.
 
-There is no automatic prerelease migration or fallback path in v1.
+There is no automatic prerelease migration or fallback path.
 
 TradingCodex releases software; they do not promote a model policy or establish
 investment-performance claims. Those claims require the independent evidence
@@ -183,8 +189,8 @@ also require the disposable-workspace and Codex-native checks documented in
 `.github/workflows/ci.yml` is test-only. Parallel Ubuntu jobs run the frontend
 determinism check and the Python 3.11 source/framework gates. It does
 not construct or upload a wheel or source distribution, run release-upgrade or
-native-runtime matrices, or publish anything. Documentation-, guide-, OpenWiki-,
-and asset-only pushes or pull requests skip this workflow. Source-bearing pull
+native-runtime matrices, or publish anything. Documentation-, guide-, and
+asset-only pushes or pull requests skip this workflow. Source-bearing pull
 requests and pushes still receive the normal source-quality checks.
 
 `.github/workflows/release.yml` is manual-only. Every run requires an explicit
@@ -297,14 +303,14 @@ uvx --refresh --from "tradingcodex==$ReleaseVersion" tcx attach . --from "tradin
 Verify the PyPI project page, filenames, metadata, and release notes after the
 smokes pass.
 
-## v1 Update Policy
+## v2 Update Policy
 
-TradingCodex has two update layers within the v1 line:
+TradingCodex has two update layers within the v2 line:
 
 - package update: run the desired package with `uvx --refresh`, upgrade an
   installed `uv` tool, or use `install.sh --update`
 - workspace update: run `tcx update <workspace>` from that package to refresh
-  generated files, indexes, project MCP configuration, hooks, and the v1 schema
+  generated files, indexes, project MCP configuration, hooks, and the v2 schema
 
 `tcx update` preserves workspace identity and workspace-native user artifacts.
 It may replace only generated paths owned by
@@ -313,7 +319,7 @@ Codex and open a new task so project configuration, prompts, skills, hooks, and
 MCP state reload together.
 
 A future major-version migration requires its own explicit product contract and
-validation. v1 release automation does not infer one.
+validation. Release automation does not infer one.
 
 ## What Is Not Deployed