tradingcodex 0.3.0__tar.gz → 0.3.2__tar.gz

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.3.0
+Version: 0.3.2
 Summary: Agentic investment workflow harness for Codex-native research and service-gated execution checks.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
@@ -62,7 +62,7 @@ research, thesis review, portfolio/risk handoffs, and service-gated execution
 checks. Codex coordinates the work, specialist agents own bounded judgments,
 and TradingCodex keeps execution behind explicit service gates.
 
-[Start Skills](#start-with-these-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+[User-Facing Skills](#user-facing-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
@@ -83,17 +83,23 @@ comes only from installed, reviewed providers and explicit live gates.
 
 ---
 
-## Start With These Skills
+## User-Facing Skills
 
-TradingCodex is easiest to use by choosing the right user-facing entry skill:
+TradingCodex is easiest to use by choosing the right user-facing skill:
 
-| Start skill | Use when | Stops before |
+| Primary skill | Use when | Stops before |
 | --- | --- | --- |
 | `tcx-workflow` | Investment research, thesis review, Decision Packages, portfolio fit, risk review, or order-readiness workflow planning. | Substantive synthesis before accepted role artifacts; approval or execution without service gates. |
 | `strategy-creator` | Turning user rules into reusable strategy skills, updating strategy criteria, activating, archiving, or inspecting strategy state. | Live ticker analysis, recommendation, order approval, execution, or policy changes. |
 | `tcx-server` | Checking dashboard/service health, doctor output, update status, MCP readiness, DB path, or startup recovery. | Investment judgment, broker execution, raw secrets, or template edits. |
 | `tcx-build` | Build-mode connector/provider work, broker/API scaffolding, capability profile wiring, credential-ref setup, and validation. | Raw secret handling, live order submission, or investment subagent dispatch. |
 
+| Supporting skill | Use when | Main output |
+| --- | --- | --- |
+| `plan-workflow` | You want an explicit workflow plan before role dispatch or implementation. | Bounded plan with selected stages, roles, gates, and waiting/revise/blocked posture. |
+| `automate-workflow` | You want to define a repeatable workflow automation without executing trades. | Automation recipe, trigger scope, guardrails, and review requirements. |
+| `postmortem` | A workflow, decision, artifact, or execution/process step needs review after the fact. | Failure analysis, missed assumptions, source-quality lessons, and future warning patterns. |
+
 Most investment prompts enter through natural language, then the hook writes
 compact intake and `head-manager` uses `tcx-workflow` to draft, validate, and
 record the staged plan before dispatch. See
@@ -176,17 +182,17 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 ## Architecture
 
 ```mermaid
-flowchart TD
-  U["User prompt"] --> H["Codex head-manager"]
-  H --> R["Fixed role agents"]
-  R --> A["Accepted artifacts"]
-  A --> J["judgment-reviewer"]
-  J --> D["Decision Package"]
-  D --> S["Django service plane"]
-  S --> G["Policy / approval / audit gates"]
-  G --> E["Paper execution or gated live provider"]
-  S --> W["Web / Admin / API / MCP / CLI"]
-  S --> M["File-native research memory"]
+flowchart LR
+  user([User prompt]) --> manager[Head manager]
+  manager --> agents[Fixed role agents]
+  agents --> artifacts[Accepted artifacts]
+  artifacts --> reviewer[Judgment reviewer]
+  reviewer --> decision[Decision Package]
+  decision --> service[Django service plane]
+  service --> gates[Policy approval audit gates]
+  gates --> execution[Paper execution or gated live provider]
+  service --> surfaces[Web Admin API MCP CLI]
+  service --> memory[File native research memory]
 ```
 
 The architecture is intentionally small: Codex owns coordination and role
@@ -223,7 +229,7 @@ provide investment recommendations or guarantee returns.
 | Status | Milestone |
 | --- | --- |
 | Shipped | Generated Codex workspace, fixed role roster, project MCP config, Django service plane, local web dashboard, Admin, Ninja API, file-native research memory, component registry, policy/audit primitives. |
-| Current `0.3.0` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop, provider capability profiles, and Python `>=3.11,<3.15` support. |
+| Current `0.3.2` | Brief research chat replies with saved head-manager synthesis reports, Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop closure state, Evidence Run/Validation Cards, provider capability profiles, and Python `>=3.11,<3.15` support. |
 | Next | Deeper validation scenarios, richer provider capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
 | Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and broker-specific live providers only after explicit product, policy, adapter, and validation work. |
 
@@ -239,7 +245,7 @@ validation, and release policy.
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
 | [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
-| [User-facing skills](docs/user-facing-skills.md) | Which skill starts which user workflow and what each entrypoint must not do. |
+| [User-facing skills](docs/user-facing-skills.md) | Which primary or supporting skill fits each user workflow and what each must not do. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
 | [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Workspace orchestration model](docs/harness.md) | Top-level workflow model, components, guardrails, improvement, and naming rules. |

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/README.md

@@ -31,7 +31,7 @@ research, thesis review, portfolio/risk handoffs, and service-gated execution
 checks. Codex coordinates the work, specialist agents own bounded judgments,
 and TradingCodex keeps execution behind explicit service gates.
 
-[Start Skills](#start-with-these-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
+[User-Facing Skills](#user-facing-skills) | [Quick Start](#installation) | [Architecture](#architecture) | [Docs](docs/README.md) | [Safety](docs/safety-policy-and-execution.md) | [Contributing](CONTRIBUTING.md) | [License](LICENSE)
 
 <p align="center">
   <img src="assets/tradingcodex-banner.svg" alt="TradingCodex" width="100%">
@@ -52,17 +52,23 @@ comes only from installed, reviewed providers and explicit live gates.
 
 ---
 
-## Start With These Skills
+## User-Facing Skills
 
-TradingCodex is easiest to use by choosing the right user-facing entry skill:
+TradingCodex is easiest to use by choosing the right user-facing skill:
 
-| Start skill | Use when | Stops before |
+| Primary skill | Use when | Stops before |
 | --- | --- | --- |
 | `tcx-workflow` | Investment research, thesis review, Decision Packages, portfolio fit, risk review, or order-readiness workflow planning. | Substantive synthesis before accepted role artifacts; approval or execution without service gates. |
 | `strategy-creator` | Turning user rules into reusable strategy skills, updating strategy criteria, activating, archiving, or inspecting strategy state. | Live ticker analysis, recommendation, order approval, execution, or policy changes. |
 | `tcx-server` | Checking dashboard/service health, doctor output, update status, MCP readiness, DB path, or startup recovery. | Investment judgment, broker execution, raw secrets, or template edits. |
 | `tcx-build` | Build-mode connector/provider work, broker/API scaffolding, capability profile wiring, credential-ref setup, and validation. | Raw secret handling, live order submission, or investment subagent dispatch. |
 
+| Supporting skill | Use when | Main output |
+| --- | --- | --- |
+| `plan-workflow` | You want an explicit workflow plan before role dispatch or implementation. | Bounded plan with selected stages, roles, gates, and waiting/revise/blocked posture. |
+| `automate-workflow` | You want to define a repeatable workflow automation without executing trades. | Automation recipe, trigger scope, guardrails, and review requirements. |
+| `postmortem` | A workflow, decision, artifact, or execution/process step needs review after the fact. | Failure analysis, missed assumptions, source-quality lessons, and future warning patterns. |
+
 Most investment prompts enter through natural language, then the hook writes
 compact intake and `head-manager` uses `tcx-workflow` to draft, validate, and
 record the staged plan before dispatch. See
@@ -145,17 +151,17 @@ workflow has earned. Weak, stale, missing, or out-of-scope upstream work returns
 ## Architecture
 
 ```mermaid
-flowchart TD
-  U["User prompt"] --> H["Codex head-manager"]
-  H --> R["Fixed role agents"]
-  R --> A["Accepted artifacts"]
-  A --> J["judgment-reviewer"]
-  J --> D["Decision Package"]
-  D --> S["Django service plane"]
-  S --> G["Policy / approval / audit gates"]
-  G --> E["Paper execution or gated live provider"]
-  S --> W["Web / Admin / API / MCP / CLI"]
-  S --> M["File-native research memory"]
+flowchart LR
+  user([User prompt]) --> manager[Head manager]
+  manager --> agents[Fixed role agents]
+  agents --> artifacts[Accepted artifacts]
+  artifacts --> reviewer[Judgment reviewer]
+  reviewer --> decision[Decision Package]
+  decision --> service[Django service plane]
+  service --> gates[Policy approval audit gates]
+  gates --> execution[Paper execution or gated live provider]
+  service --> surfaces[Web Admin API MCP CLI]
+  service --> memory[File native research memory]
 ```
 
 The architecture is intentionally small: Codex owns coordination and role
@@ -192,7 +198,7 @@ provide investment recommendations or guarantee returns.
 | Status | Milestone |
 | --- | --- |
 | Shipped | Generated Codex workspace, fixed role roster, project MCP config, Django service plane, local web dashboard, Admin, Ninja API, file-native research memory, component registry, policy/audit primitives. |
-| Current `0.3.0` | Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop, provider capability profiles, and Python `>=3.11,<3.15` support. |
+| Current `0.3.2` | Brief research chat replies with saved head-manager synthesis reports, Codex-native Decision Packages, independent judgment-review gate, staged workflow planning, artifact-supervisor loop closure state, Evidence Run/Validation Cards, provider capability profiles, and Python `>=3.11,<3.15` support. |
 | Next | Deeper validation scenarios, richer provider capability profiles, stronger generated-workspace smoke coverage, and improved artifact quality tooling. |
 | Future | Separately governed verified adapters, hosted/managed services, enterprise policy/compliance packs, and broker-specific live providers only after explicit product, policy, adapter, and validation work. |
 
@@ -208,7 +214,7 @@ validation, and release policy.
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
 | [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
-| [User-facing skills](docs/user-facing-skills.md) | Which skill starts which user workflow and what each entrypoint must not do. |
+| [User-facing skills](docs/user-facing-skills.md) | Which primary or supporting skill fits each user workflow and what each must not do. |
 | [Core concepts and rules](docs/core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, roles, execution lifecycle, and research memory. |
 | [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
 | [Workspace orchestration model](docs/harness.md) | Top-level workflow model, components, guardrails, improvement, and naming rules. |

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/README.md

@@ -42,7 +42,7 @@ If these layers disagree, treat `docs/` as the durable product intent and fix th
 
 | Document | Owns |
 | --- | --- |
-| [user-facing-skills.md](./user-facing-skills.md) | User-facing entry skills, routing posture, and non-entrypoint skill boundaries. |
+| [user-facing-skills.md](./user-facing-skills.md) | User-facing primary and supporting skills, routing posture, and role-owned skill boundaries. |
 | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md) | Fixed role roster, no-overlap role contract, head-manager dispatch gate, skills, strategy skills, subagent isolation, workflow routing, and module graph. |
 | [research-memory-and-artifacts.md](./research-memory-and-artifacts.md) | File-native research memory, source snapshots, artifact paths, readiness labels, report quality floor, forecast ledger posture, and handoff metadata. |
 | [financial-workflow-references.md](./financial-workflow-references.md) | Research-backed finance workflow principles and non-expert UX requirements for workflow intake and handoffs. |
@@ -54,7 +54,7 @@ If these layers disagree, treat `docs/` as the durable product intent and fix th
 | --- | --- |
 | [guardrails.md](./guardrails.md) | Guardrail taxonomy: guidance, enforcement, and information barriers. |
 | [safety-policy-and-execution.md](./safety-policy-and-execution.md) | Permission checks, approval rules, execution lifecycle, adapter boundary, external MCP gate, blocked actions, and secret handling. |
-| [improvement-loop.md](./improvement-loop.md) | Workflow quality, research memory, skill evolution, postmortems, validation feedback, and quality-learning loops. |
+| [improvement-loop.md](./improvement-loop.md) | Workflow quality, research memory, improve records, skill evolution, postmortem review, validation feedback, and quality-learning loops. |
 
 ## Implementation And Operations Documents
 

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/artifact-supervisor-loop-prd.md

@@ -40,6 +40,9 @@ context discipline, approval gates, execution boundaries, and user scope.
   escalation-only sets.
 - Extend research artifact metadata with explicit follow-up requests, trigger
   types, materiality, suggested consent posture, and loop provenance.
+- Let artifacts preserve `improvements` so repeated investment judgment
+  findings can feed `improve` review and later workflows instead of hidden
+  prompt drift.
 - Store loop state as file-native workspace state for Codex inspection,
   context-budget audit, product web preview, concurrent Codex app threads, and
   postmortems.
@@ -370,6 +373,7 @@ Canonical run-state shape:
   "completed_artifacts": [],
   "loop_decisions": [],
   "escalation_proposals": [],
+  "improvements": [],
   "blocked_actions": [],
   "stop_reason": ""
 }
@@ -413,6 +417,8 @@ Update these surfaces together:
 - Product web
   - preview loop state, follow-up requests, escalation proposals, and blocked
     actions without spawning agents, approving orders, or executing orders.
+  - show improve records as analysis-memory review items without applying
+    skill, policy, prompt, validation, approval, broker, or execution changes.
   - first release escalation proposals are read-only; escalation approval stays
     Codex-prompt or CLI driven with explicit user wording captured in audit.
 

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/components.md

@@ -37,10 +37,10 @@ paths clear.
 | --- | --- | --- |
 | `investment-request-routing` | Classifies user intent and activates fixed-role workflows. | `guardrail.guidance`, `improvement.workflow_quality` |
 | `fixed-role-dispatch` | Maintains head-manager, fixed subagent routing, and no-overlap handoff boundaries. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality` |
-| `research-memory` | Stores source-aware research artifacts, versions, snapshots, and exports. | `improvement.research_memory` |
+| `research-memory` | Stores source-aware research artifacts, versions, snapshots, Evidence Run Cards, Validation Cards, and exports. | `improvement.research_memory` |
 | `workflow-quality-gates` | Defines lane selection, Artifact Supervisor Loop policy, Decision Quality Spine, agent judgment review, handoff acceptance, artifact readiness, claim discipline, and synthesis gates. | `guardrail.guidance`, `improvement.workflow_quality` |
 | `decision-package` | Wraps workflow plans, artifact paths, profile gaps, blocked actions, and next steps in Codex-readable workspace markdown. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
-| `artifact-quality-contract` | Evaluates workspace artifacts and forecast ledgers for source/as-of posture, source trust, claim tags, handoff state, confidence, missing evidence, judgment-review fields, and next-recipient routing metadata. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
+| `artifact-quality-contract` | Evaluates workspace artifacts, Evidence Run Cards, Validation Cards, source snapshots, and forecast ledgers for source/as-of posture, source trust, data-boundary warnings, claim tags, handoff state, confidence, missing evidence, judgment-review fields, and next-recipient routing metadata. | `guardrail.guidance`, `improvement.workflow_quality`, `improvement.research_memory` |
 | `context-efficiency-contract` | Keeps workflows bounded through compact briefs, artifact references, context summaries, source snapshot IDs, targeted full-artifact reads, and `subagents context-audit` validation. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality`, `improvement.context_efficiency` |
 | `responsibility-boundary-contract` | Separates durable role identity, tool permissions, skill procedures, artifact contracts, and projection ownership so changes stay local. | `guardrail.guidance`, `guardrail.information_barrier`, `improvement.workflow_quality`, `improvement.skill_evolution` |
 | `external-data-source-gate` | Keeps external evidence read-only and source-aware. | `guardrail.guidance`, `improvement.workflow_quality` |
@@ -52,7 +52,7 @@ paths clear.
 | `execution-boundary` | Keeps execution behind role action allowlists, approval, duplicate-request, connection, and audit checks. | `guardrail.enforcement`, `guardrail.information_barrier` |
 | `audit-ledger` | Records policy, MCP, order, approval, execution, and hook events. | `guardrail.enforcement`, `improvement.validation_feedback` |
 | `skill-improvement-loop` | Keeps core skills, strategy skills, and role-local optional skill files visible through validation, generated manifests, and read-only status. | `improvement.skill_evolution`, `guardrail.guidance` |
-| `postmortem-loop` | Turns rejected orders, process failures, thesis changes, artifact-loop blocks/escalations, and executions into improvements. | `improvement.postmortems`, `improvement.validation_feedback` |
+| `postmortem-loop` | Turns rejected orders, process failures, thesis changes, artifact-loop blocks/escalations, and executions into improve records for later judgment review. | `improvement.postmortems`, `improvement.validation_feedback` |
 | `paper-execution` | Provides experimental local paper and validation-only execution paths behind the approved action boundary. | `guardrail.enforcement` |
 
 ## Runtime Surfaces

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/core-concepts-and-rules.md

@@ -96,6 +96,9 @@ subagents. Detailed responsibilities live in
 Handoff states are `accepted`, `revise`, `blocked`, or `waiting`. Only accepted
 artifacts move downstream. `head-manager` may synthesize accepted outputs and
 conflicts, but must not repair missing specialist work with direct analysis.
+When synthesis is allowed, the full user-facing synthesis should be saved as a
+workspace Markdown report; the chat reply should stay brief and point to that
+report.
 
 ## Execution Lifecycle Snapshot
 

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/deployment.md

@@ -88,7 +88,8 @@ cd /tmp/tcx-smoke
 
 ## CI/CD
 
-CI is defined in `.github/workflows/ci.yml`.
+CI is defined in `.github/workflows/ci.yml` and appears as
+`CI (no deploy)` in GitHub Actions.
 
 It runs on pull requests and pushes to `main` or `develop`:
 
@@ -97,10 +98,14 @@ It runs on pull requests and pushes to `main` or `develop`:
 - runs `python manage.py check`
 - checks that migrations are current
 - compiles Python sources
-- builds the package
+- builds the package for validation only
 - validates distribution metadata with `twine check`
 
-Release automation is defined in `.github/workflows/release.yml`.
+The CI workflow never uploads to TestPyPI or PyPI. Pushes to `main` or
+`develop` run tests and packaging checks only.
+
+Release automation is defined in `.github/workflows/release.yml` and appears as
+`Manual Release` in GitHub Actions.
 
 The release workflow is manual-only. Branch pushes and tag pushes must not
 publish package artifacts to TestPyPI or PyPI.
@@ -134,7 +139,7 @@ Product flows create, check, approve, and submit `OrderTicket` records directly.
 Use TestPyPI before the first public PyPI release and after packaging changes.
 
 1. Confirm the local build verification steps pass.
-2. Run the `Release` workflow manually with `publish_testpypi=true`.
+2. Run the `Manual Release` workflow manually with `publish_testpypi=true`.
 3. Install from TestPyPI in a clean environment.
 
 Example:
@@ -144,7 +149,7 @@ python3.11 -m venv /tmp/tcx-testpypi
 /tmp/tcx-testpypi/bin/pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  tradingcodex==0.3.0
+  tradingcodex==0.3.2
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -165,15 +170,15 @@ Before pushing the release tag:
 - run local build verification
 - run a TestPyPI release when packaging changed
 
-Then create or update the GitHub release/tag as needed, and run the `Release`
-workflow manually with `publish_pypi=true`. Do not rely on tag push for
+Then create or update the GitHub release/tag as needed, and run the
+`Manual Release` workflow manually with `publish_pypi=true`. Do not rely on tag push for
 publication; tag pushes are intentionally non-publishing.
 
 After the PyPI workflow completes:
 
 ```bash
 python3.11 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.3.0
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.3.2
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -270,7 +275,11 @@ Use PEP 440 versions:
 - `0.3.0` for the independent judgment-review gate, staged workflow routing
   cleanup, Decision Quality Spine hardening, and source-aware thesis lifecycle
   updates after `0.2.10`
-- later patch releases for compatible fixes after `0.3.0`
+- `0.3.1` for compatible evidence-card validation and persisted loop closure
+  state fixes after `0.3.0`
+- `0.3.2` for brief research chat replies with saved head-manager synthesis
+  reports after `0.3.1`
+- later patch releases for compatible fixes after `0.3.2`
 - pre-releases such as `0.4.0a1`, `0.4.0b1`, or `0.4.0rc1` when preparing
   the next minor contract
 

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/financial-workflow-references.md

@@ -24,7 +24,7 @@ drafting, approval, or execution.
 | Strategic allocation depends on horizon and risk tolerance | Long-horizon workflows should treat time horizon and loss capacity as required context, not afterthoughts. | Campbell and Viceira (2002) |
 | Investment policy is objectives plus constraints | Portfolio workflows should frame recommendations against return/risk objectives, liquidity, time horizon, tax, legal/regulatory, and unique constraints. | CFA Institute investment policy statement guidance |
 | Planning is a process, not a one-shot answer | Beginner-facing UX should show workflow stage, next evidence needed, and blocked actions before presenting outputs as advice. | CFP Board financial planning process |
-| Each workflow should make later workflows easier | Role artifacts should preserve reusable context summaries, reader summaries, source snapshots, missing-evidence notes, and improvement proposals instead of making future agents rediscover the same gaps. | Every compound engineering guide; Will Larson commentary |
+| Each workflow should make later workflows easier | Role artifacts should preserve reusable context summaries, reader summaries, source snapshots, missing-evidence notes, and improve records instead of making future agents rediscover the same gaps. | Every compound engineering guide; Will Larson commentary |
 | Agentic work should be a bounded loop, not open-ended autonomy | TradingCodex workflows may repeat evidence gathering, artifact verification, synthesis, and memory capture, but every lane must expose stop conditions and blocked actions. | Recent loop-engineering practice across Codex, Claude Code, OpenClaw, and memory-layer frameworks |
 | Loop reliability depends on the verifier | Every workflow lane should name what gets checked after each pass: artifact quality, source freshness, profile gaps, and blocked actions. Failed checks return `revise`, `blocked`, or `waiting` rather than widening the lane. | Addy Osmani loop-engineering framing; recent verifier/budget loop guidance |
 | Financial agent teams need explicit opposition | Decision-support synthesis should test the favorable case against a bearish or skeptical case, stale data, missing profile context, policy conflicts, and selected-strategy conflicts before naming a decision state. | TradingAgents bull/bear researcher debate; risk management team |
@@ -46,7 +46,13 @@ drafting, approval, or execution.
 | [IOSCO AI/ML report for market intermediaries and asset managers](https://www.iosco.org/library/pubdocs/pdf/IOSCOPD684.pdf) | AI-assisted capital-markets features need governance, testing, monitoring, data-quality controls, explainability, and outsourcing/third-party oversight posture. |
 | [SEC Plain English Handbook](https://www.sec.gov/pdf/handbook.pdf) | User-facing screens should start with plain-English workflow meaning before professional evidence, assumptions, caveats, and artifacts. |
 | [Every, "Compound Engineering"](https://every.to/guides/compound-engineering) | Engineering work should teach the system reusable capabilities; TradingCodex applies this by making role outputs preserve compact context, reader summaries, source posture, and missing-evidence notes for future workflows. |
-| [Will Larson, "Learning from Every's Compound Engineering"](https://lethain.com/everyinc-compound-engineering/) | The useful pattern is separating research/planning, work, review, and compounding lessons; TradingCodex mirrors that with starter intake, role artifacts, quality checks, and improvement proposals. |
+| [Will Larson, "Learning from Every's Compound Engineering"](https://lethain.com/everyinc-compound-engineering/) | The useful pattern is separating research/planning, work, review, and compounding memory; TradingCodex mirrors that with starter intake, role artifacts, quality checks, postmortem review, and improve records. |
+| [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs/) and [Hermes skills system](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Self-improvement should be procedural and user/profile-owned: durable memory and skills live outside the package update path, load on demand, and improve through explicit writable artifacts rather than hidden model-weight changes. TradingCodex adapts this as workspace-owned improve records and indexes. |
+| [Hermes Honcho memory docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho) | Long-term personalization works best as a bounded context layer with cadence, budget, and profile/session isolation. TradingCodex keeps improve memory workspace-scoped, compact, and read-only for future judgment until explicit maintenance applies changes. |
+| [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) | Language feedback can improve future trials without model fine-tuning. TradingCodex stores reflective improve records as reviewable investment-judgment memory, not automatic policy or prompt mutation. |
+| [Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651) | Iterative feedback/refinement can improve outputs at test time. TradingCodex maps this to artifact revision, waiting, blocked, and accepted handoff states. |
+| [Voyager](https://arxiv.org/abs/2305.16291) and [MemGPT](https://arxiv.org/abs/2310.08560) | Skill libraries and hierarchical memory show why compact retrieval layers matter. TradingCodex keeps raw improve history append-only and uses `improve-index.json` for marginal reuse. |
+| [A-MEM: Agentic Memory for LLM Agents](https://arxiv.org/abs/2502.12110) and [GEPA](https://arxiv.org/html/2507.19457v1) | Dynamic indexing/linking and trace-driven reflection inform the improve index shape, but TradingCodex stops short of autonomous prompt evolution because finance workflows need explicit audit and approval boundaries. |
 | [Addy Osmani, "Loop Engineering"](https://addyosmani.com/blog/loop-engineering/) | A useful agentic loop combines automations, isolated workspaces, skills, connectors, subagents, and durable external memory; TradingCodex maps these to workflow intake, fixed subagents, MCP/service boundaries, artifacts, and generated workspace state. |
 | [Business Insider, "Forget prompt engineering: Loop engineering is all the rage now"](https://www.businessinsider.com/what-are-loops-ai-engineering-tips-2026-6) | Current loop-engineering discourse emphasizes designing recurring systems that prompt agents, with cost and oversight tradeoffs; TradingCodex exposes loop controls and token/context budgets rather than unlimited autonomy. |
 | [Anthropic Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills) | Recent agent tooling exposes loops through reusable skills, bundled `/loop`, subagent execution, and dynamic context; TradingCodex mirrors the reusable-skill and fixed-subagent pattern without depending on Claude Code. |
@@ -91,7 +97,7 @@ or execute trades. It should:
 - instruct agents to write plain-English first, then professional evidence,
   assumptions, and caveats
 - instruct agents to preserve reusable context, source snapshots, missing
-  evidence, tests, or improvement proposals when a lesson should compound into
+  evidence, tests, or improve records when a finding should compound into
   future workflows
 
 Loop engineering applies only inside the workflow boundary selected at intake.

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/generated-workspaces.md

@@ -101,7 +101,7 @@ Generated workspaces contain:
 - an immutable workspace manifest at `.tradingcodex/workspace.json`
 - root `head-manager` identity loaded from `.codex/prompts/base_instructions/head-manager.md` through `.codex/config.toml` `model_instructions_file`
 - sectioned Markdown base-instruction format for `head-manager`, including `# How you work`, TradingCodex guardrails, and tool guidelines
-- Codex-style operating style in the root `head-manager` prompt: scoped `AGENTS.md` handling, concise preambles, selective planning, `rg`-first search, `apply_patch` edits, focused validation, dirty-worktree respect, and concise final handoffs
+- Codex-style operating style in the root `head-manager` prompt: scoped `AGENTS.md` handling, concise preambles, selective planning, `rg`-first search, `apply_patch` edits, focused validation, dirty-worktree respect, concise maintenance handoffs, and brief chat replies that point to saved head-manager synthesis reports once accepted artifacts exist
 - instruction/skill separation: root `head-manager` instructions own identity, durable safety boundaries, fail-closed dispatch, role boundaries, skill routing, optional-skill management, and approved action boundaries; fixed subagent TOML files own standing role identity, MCP/tool config, artifact walls, and always-on 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
 - 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
 - validated staged workflow plan: hook intake hints are not binding; `$tcx-workflow`
@@ -144,6 +144,12 @@ Generated workspaces contain:
   validated stages, selected team, allowed follow-up team, loop policy, pending
   tasks, planner decisions, escalation proposals, blocked actions, and stop reason
   without spawning subagents recursively
+- `improve` ledger records under `.tradingcodex/mainagent/improve.jsonl`,
+  plus incremental summaries and dedupe state in
+  `.tradingcodex/mainagent/improve-index.json`, fed by artifact
+  `improvements`, postmortem review, and selected loop feedback; these records
+  are reusable investment-judgment context and never apply prompt, skill,
+  policy, MCP, broker, approval, or execution changes
 - Codex session/thread routing map:
   `.tradingcodex/mainagent/session-workflow-runs.json` maps a Codex app session
   key to the active `workflow_run_id`, so two app threads in one attached

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/harness.md

@@ -48,7 +48,7 @@ TradingCodex Harness
 | State | Keep execution-sensitive runtime state in the central Django DB, while Codex-native agent, skill, and research handoff state is workspace-file state. |
 | Interfaces | Expose Web, Admin, REST, CLI, and MCP as service-layer callers. |
 | Guardrails | Reduce, restrict, or block risky actions through guidance, enforcement, and information barriers. |
-| Improvement | Raise workflow quality through no-overlap handoff contracts, quality gates, artifact readiness, research memory, postmortems, and test feedback. |
+| Improvement | Raise workflow quality through no-overlap handoff contracts, quality gates, artifact readiness, research memory, improve records, postmortem review, and test feedback. |
 | Approved action boundary | Keep executable actions behind policy, approval, duplicate-request, connection, and audit checks. |
 | Decision packages | Keep investment ideas Codex-native by packaging workflow plans, artifact paths, source trust notes, thesis lifecycle state, profile gaps, blocked actions, and next allowed actions as workspace markdown. Non-investment workflow packages such as connector build or strategy authoring use workflow lifecycle state instead of thesis lifecycle or portfolio/risk language. |
 | Provenance | Record which workspace and role produced or requested work without making workspaces separate ledgers. |
@@ -89,7 +89,8 @@ They are tags and review lenses applied to components.
 - Information barriers limit role knowledge, file access, secrets, and tool surfaces.
 
 Guardrails never replace the need for improvement. A blocked action can still
-leave behind a useful postmortem, skill proposal, or validation scenario.
+leave behind a useful improve record, postmortem review, skill proposal, or
+validation scenario.
 
 ## Improvement Under Harness
 
@@ -98,6 +99,9 @@ It is a tag and review lens applied to components.
 
 - Workflow maps route work to the right role team.
 - Quality gates define evidence, source/as-of posture, claim discipline, handoff acceptance, and readiness.
+- Improve records preserve reusable analysis memory from artifacts,
+  postmortem review, and loop feedback without changing prompts, skills, policy,
+  broker, approval, or execution authority.
 - Handoff contracts keep downstream roles from filling missing upstream work outside their owned question.
 - Research memory preserves workspace markdown artifacts, versions, source posture, and source snapshots.
 - Skill proposals let the harness evolve without hidden prompt drift.
@@ -154,5 +158,5 @@ file internals belong in collapsed diagnostics unless the user opens them.
 ## Naming Rule
 
 Use "harness" for the top-level operating model. Use "guardrail" only for
-safety/restriction systems. Use "improvement" for quality, learning, skill,
-postmortem, and validation loops.
+safety/restriction systems. Use "improvement" for quality, investment judgment
+learning, skill, postmortem, and validation loops.

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/improvement-loop.md

@@ -1,8 +1,14 @@
 # Improvement Loop
 
 Improvement is the quality subsystem under the top-level TradingCodex workspace orchestration model.
-It makes future workflows better through routing discipline, artifact quality,
-research memory, skill proposals, postmortems, and validation feedback.
+For investment workflows, self-improvement means better investment judgment:
+clearer evidence, assumptions, source posture, valuation sensitivity, risk
+context, and decision readiness. It is not hidden prompt, skill, policy, broker,
+approval, or execution mutation.
+
+The broader harness also supports explicit skill proposals and validation
+feedback, but those are deliberate maintenance paths, not automatic investment
+workflow self-modification.
 
 Improvement is separate from Guardrails. Improvement can raise confidence and
 reduce repeated mistakes, but it never authorizes execution by itself.
@@ -84,6 +90,43 @@ proposal -> validation -> approval -> apply -> audit
 This keeps improvements visible through Admin, CLI, tests, and docs instead of
 letting hidden prompt changes become durable product rules.
 
+## Improve Ledger
+
+TradingCodex uses the memory pattern from self-improving agent systems, but the
+thing being improved is investment judgment: evidence discipline, source
+quality, assumptions, valuation sensitivity, forecast calibration, risk misses,
+portfolio-context gaps, contradictions, and decision readiness. It does not let
+an agent silently rewrite durable prompts, roles, policy, MCP allowlists, broker
+posture, approvals, execution gates, or skills during an investment workflow.
+
+Research artifacts may include `improvements` frontmatter. Postmortem review and
+the Artifact Supervisor Loop can also record selected feedback such as blocked
+artifacts, lane-escalation proposals, and exhausted follow-up budgets. Recorded
+improvements are stored under `.tradingcodex/mainagent/improve.jsonl`, with a
+compact `.tradingcodex/mainagent/improve-index.json` beside it.
+Each record carries source path, improvement type, materiality, reason, evidence refs,
+review state, reuse state, and the fixed authority boundary
+`no_policy_skill_or_execution_change`.
+
+The JSONL ledger is the append-only workspace-owned audit trail. The index is
+the incremental reuse layer: counts by type, role, materiality, and source type,
+recent compact summaries, recent full records, known improvement ids for dedupe,
+and the ledger file marker used to rebuild once after legacy or manual edits.
+Future `tcx workflow improve` runs read the compact index instead of rereading
+the entire ledger unless the index is missing or stale.
+
+The ledger is inspired by Hermes-style procedural memory and GEPA-style
+trace-driven reflection, but TradingCodex keeps the application rule simple:
+
+```text
+trace/artifact/postmortem -> improve record -> future judgment review -> audit
+```
+
+Improve records are not system changes. They are compact investment-analysis memory for
+future workflows. Skill changes still use optional skill CRUD or skill proposal
+projection. Policy, role, approval, execution, broker, and secret surfaces still
+use their existing service-layer gates.
+
 ## Postmortems
 
 Postmortems are not only for executed orders. They also apply to:
@@ -101,12 +144,12 @@ Postmortems are not only for executed orders. They also apply to:
 A useful postmortem should include an investment judgment review: original
 thesis, what happened, failed assumption, role evidence miss or overstatement,
 stale or misleading source, confidence calibration, and future warning pattern.
-It should end with concrete harness, guardrail, policy, skill, artifact, or
-validation improvements.
+It should end with concrete `improve` records about investment judgment,
+analysis readiness, source quality, assumptions, risk, or evidence gaps.
 
 ## Validation Feedback
 
-Validation feedback turns lessons into regression coverage:
+Validation feedback turns improve findings into regression coverage:
 
 - unit tests for policy and execution preconditions
 - API tests for Admin/Ninja/MCP boundaries

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/interfaces-and-surfaces.md

@@ -352,7 +352,7 @@ Top-level commands:
 - `tcx profile status|list|create|select|update`
 - `tcx subagents status|list|inspect|diff|project|plan|loop|skills|prompt|state`
 - `tcx skills list [--all]|inspect|propose-add|propose-update|apply-proposal`
-- `tcx research create|append|get|list|search|export`
+- `tcx research create|append|get|list|search|export|run-card|validation-card`
 - `tcx policy simulate`
 - `tcx db status|path|migrate`
 - `tcx mcp call <tool> [tool args]`
@@ -394,7 +394,7 @@ provider, then registration stores only provider metadata and `credential_ref`.
 - `./tcx db status|path|migrate`
 - `./tcx mcp call <tool>`
 - `./tcx mcp ledger [--tool <name>]`
-- `./tcx research create|append|get|list|search|export`
+- `./tcx research create|append|get|list|search|export|run-card|validation-card`
 
 Default main-agent skill listing is user-facing, not exhaustive. It shows only
 direct user entrypoints: `plan-workflow`, `tcx-workflow`, `automate-workflow`,

{tradingcodex-0.3.0 → tradingcodex-0.3.2}/docs/product-direction.md

@@ -74,7 +74,7 @@ guidance emitted by the product should remain English.
 | Strong role model | Keep one `head-manager`, ten fixed subagents, and role-owned skills as a durable coordination model, including an independent judgment-review gate. |
 | Multi-universe extensibility | Let public equity be deepest first while preserving paths for ETF/index, crypto, macro/rates/FX/commodities, options, credit-signal, and cross-asset workflows. |
 | Intuition-led investing with gates | Let users begin from rough market intuition, then translate that intuition into workflow lane, role team, evidence needs, investor-profile questions, blocked actions, and next allowed actions. |
-| Compounding workflow memory | Each completed workflow should leave reusable context, source posture, missing-evidence notes, tests, or improvement proposals so the next workflow is easier to run and review. |
+| Compounding workflow memory | Each completed workflow should leave reusable context, source posture, missing-evidence notes, tests, or improve records so the next workflow is easier to run and review. |
 | Local operator control | Make Django Admin and Ninja useful for local/staff inspection, validation, and operation without becoming a bypass. |
 
 ## Non-Goals In Detail