tradingcodex 1.2.2__tar.gz → 2.1.0__tar.gz

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

@@ -2,6 +2,32 @@
 
 ## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 1.2.2
+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.2 → 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.2/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.2 → 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

{tradingcodex-1.2.2 → 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.2 → 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.2 → 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
 

{tradingcodex-1.2.2 → tradingcodex-2.1.0}/docs/generated-workspaces.md

@@ -20,7 +20,7 @@ binding load together. Start a new task after restart rather than resuming an
 already-open task, which can retain the prior generated hook snapshot.
 
 The template source tree may be refactored for maintainability, but generated
-output paths are the v1 release contract. Module ids, module dependency
+output paths are the current release contract. Module ids, module dependency
 resolution, and rendered paths such as `.codex/config.toml`, `.agents/skills/*`,
 `.tradingcodex/*`, `trading/*`, and `./tcx` must remain stable unless docs and
 tests intentionally change the generated workspace contract. The generated
@@ -256,19 +256,19 @@ Generated workspaces contain:
 - Codex-style operating style in the root `head-manager` prompt: scoped
   `AGENTS.md` handling, concise preambles, selective planning, exact safe
   workspace reads, native `apply_patch` edits, dirty-worktree respect, concise
-  maintenance handoffs, and brief chat replies that point to saved head-manager
-  synthesis reports once accepted artifacts exist without making the saved
-  research report shallow
+  maintenance handoffs, and self-contained user answers whose saved synthesis
+  link supplements rather than replaces the conclusion and evidence
 - instruction/skill separation: root `head-manager` instructions own identity,
   root coordination, durable root safety boundaries, fail-closed dispatch,
   skill routing, optional-skill management, and approved action boundaries;
   `fixed-role.md` owns shared child safety, evidence, compact artifact, and
   evidence-backed gap handling; fixed subagent TOML files own specialist identity,
   MCP/tool config, and role-specific prohibitions; repo skills are
-  dependency-light capability procedures for workflow maps, compact
-  assignment-envelope templates, optional skill file management, quality
-  gates, synthesis, and postmortems, without declaring role ownership or
-  direct inter-skill call chains
+  canonical bundles with concise `SKILL.md` entrypoints and task-routed
+  resources at purpose-named paths. They provide dependency-light capability
+  procedures for workflow maps, compact assignment-envelope templates,
+  optional skill file management, quality gates, synthesis, and postmortems,
+  without declaring role ownership or direct inter-skill call chains
 - no-overlap handoff contract: each role owns its specialist question, downstream roles consume accepted artifacts, and missing/stale/weak upstream work returns `revise`, `blocked`, or `waiting` instead of being silently redone by another role
 - source routing: an evidence producer follows `tcx-source-gate` and hands
   compact SourceSnapshot/Dataset IDs forward. A Dataset is created only for
@@ -389,12 +389,11 @@ Generated workspaces contain:
 - verification-budget copy is task-specific: native actions, connector, and
   strategy work verifies its own service or validation evidence instead of
   research source-freshness fields
-- context-efficient research handoffs: stored markdown frontmatter includes
-  `context_summary` so downstream roles can consume artifact paths and summaries
-  before opening full markdown; bounded name-only deferred-tool discovery plus
-  at most one selected schema avoids injecting whole provider catalogs or
-  multiple schemas into context; `reader_summary` and `next_action` keep the
-  first-read experience clear for non-expert users
+- context-efficient research handoffs: compact v2 frontmatter includes one
+  shared `summary`, two readiness axes, exact IDs, and only applicable blocks;
+  receipt-only hashes and run-context digests stay out of Markdown. Bounded
+  name-only deferred-tool discovery plus at most one selected schema avoids
+  injecting whole provider catalogs or multiple schemas into context
 - lightweight analysis run state:
   `.tradingcodex/mainagent/runs/<analysis-run-id>/run.json` stores only run
   identity, request hash/size, timestamps, and sealed strategy/Investor Context
@@ -645,9 +644,10 @@ a generated-file inventory. The module lock is an exact schema: it contains
 only `format`, `schema_version`, `generated_at`, `workspace_id`,
 `tradingcodex_version`, `tradingcodex_package_spec`, `tradingcodex_home`,
 `home_source`, `tradingcodex_db_path`, `db_source`, `modules`, and
-`generated_files`. Versions use canonical PEP 440 syntax and stay within the
-running package's major version; status inspection alone may read a newer
-same-major lock so it can direct the user to refresh the package. Module entries
+`generated_files`. Versions use canonical PEP 440 syntax. Routine updates stay
+within the running package's major version; the one explicit cross-major path is
+an authenticated v1 workspace updating to v2. Status inspection alone may read
+a newer same-major lock so it can direct the user to refresh the package. Module entries
 contain exactly `id`, `description`, and `capabilities` with unique ids.
 Generated-file records contain exactly a lowercase SHA-256 and an owner of
 `template` or `projection`. Timestamps must be timezone-aware, workspace ids use
@@ -1139,8 +1139,12 @@ service, the hook separately surfaces direct Viewer and Wiki links as a Codex
 `systemMessage`. It emits no viewer URL for an incompatible or unreachable
 service. When an update is available and recommendations are not suppressed,
 the same message also includes the workspace/latest versions, workspace
-launcher command, and restart step. Update details are not added to agent
-context, and the warning never grants update authority.
+launcher command, and restart step. On `source=startup` only, the hook also
+copies that compact update message into optional `first_response_notice`
+developer context so Head Manager includes it once at the end of the first
+user-facing response; resume, clear, compact, and missing-source starts omit
+the field. The full update status is never added to agent context, and neither
+notice grants update authority.
 
 Build authorization retains `exact_first_line` and managed-skill authorization
 retains `exact_first_lines` as canonical plain-token examples for copy/paste