tradingcodex 0.2.9__tar.gz → 0.2.10__tar.gz

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tradingcodex
-Version: 0.2.9
+Version: 0.2.10
 Summary: Codex-native trading harness with a Django service plane and approved action boundary.
 Author: TradingCodex Authors
 License-Expression: Apache-2.0
@@ -265,12 +265,16 @@ provide investment recommendations or guarantee returns.
 
 ## Documentation
 
-| Document | Start here for |
+`README.md` is the product overview. The `docs/` directory is the human-readable
+source of truth for detailed product behavior, safety, architecture, workflow,
+validation, and release policy.
+
+| Start here | Use for |
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
-| [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
-| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
+| [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
 | [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. |
 | [Roles, skills, and workflows](docs/roles-skills-and-workflows.md) | Fixed role roster, no-overlap handoffs, dispatch gates, skills, and strategy behavior. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, idempotency, broker safety, secret wall, and required blocks. |

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/README.md

@@ -234,12 +234,16 @@ provide investment recommendations or guarantee returns.
 
 ## Documentation
 
-| Document | Start here for |
+`README.md` is the product overview. The `docs/` directory is the human-readable
+source of truth for detailed product behavior, safety, architecture, workflow,
+validation, and release policy.
+
+| Start here | Use for |
 | --- | --- |
 | [Installation](installation.md) | Setup, update, GitHub-main install, MCP/service startup, and smoke checks. |
-| [Docs index](docs/README.md) | Source-of-truth reading order and document ownership. |
-| [Product direction](docs/product-direction.md) | Product thesis, target user posture, goals, non-goals, runtime defaults, and scope. |
+| [Docs index](docs/README.md) | Human-readable reading paths, document ownership, and change-to-doc routing. |
 | [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. |
 | [Roles, skills, and workflows](docs/roles-skills-and-workflows.md) | Fixed role roster, no-overlap handoffs, dispatch gates, skills, and strategy behavior. |
 | [Safety policy and execution](docs/safety-policy-and-execution.md) | Permissions, approvals, idempotency, broker safety, secret wall, and required blocks. |

tradingcodex-0.2.10/docs/README.md

@@ -0,0 +1,95 @@
+# TradingCodex Documentation
+
+This directory is the human-readable source of truth linked from the public `README.md`. It explains the product model, operating rules, safety boundaries, generated workspace behavior, implementation architecture, validation expectations, release policy, and licensing posture.
+
+Use these docs when you want the deeper "why" behind TradingCodex behavior. Coding agents should use `openwiki/` for fast source navigation, then return here before changing durable product behavior.
+
+## How To Read These Docs
+
+| Reader goal | Start with | Then read |
+| --- | --- | --- |
+| Understand TradingCodex quickly | [core-concepts-and-rules.md](./core-concepts-and-rules.md) | [product-direction.md](./product-direction.md), [harness.md](./harness.md) |
+| Install or update a workspace | [../installation.md](../installation.md) | [generated-workspaces.md](./generated-workspaces.md), [deployment.md](./deployment.md) |
+| Understand the investment workflow | [harness.md](./harness.md) | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md), [research-memory-and-artifacts.md](./research-memory-and-artifacts.md) |
+| Understand safety and execution boundaries | [safety-policy-and-execution.md](./safety-policy-and-execution.md) | [guardrails.md](./guardrails.md), [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) |
+| Understand implementation architecture | [system-architecture.md](./system-architecture.md) | [interfaces-and-surfaces.md](./interfaces-and-surfaces.md), [components.md](./components.md) |
+| Change prompts, skills, hooks, routing, or generated workspaces | [roles-skills-and-workflows.md](./roles-skills-and-workflows.md) | [generated-workspaces.md](./generated-workspaces.md), [validation-and-test-plan.md](./validation-and-test-plan.md) |
+| Validate a change before release or handoff | [validation-and-test-plan.md](./validation-and-test-plan.md) | The topic document for the changed area |
+
+## Documentation Layers
+
+| Layer | Audience | Role |
+| --- | --- | --- |
+| `README.md` | New users and evaluators | Product summary, installation path, feature overview, and links into these docs. |
+| `installation.md` | Operators | Setup, update, installer, MCP/service startup, and smoke checks. |
+| `docs/` | Humans and maintainers | Durable product source of truth and deeper design rationale. |
+| `openwiki/` | Coding agents | Fast repository map and edit/validation routing. |
+| `AGENTS.md` | Coding agents | Hard rules, setup guard, coding rules, and validation requirements. |
+
+If these layers disagree, treat `docs/` as the durable product intent and fix the mismatch deliberately. Do not let hidden behavior drift live only in code, tests, prompts, skills, hooks, or generated templates.
+
+## Core Documents
+
+| Document | Owns |
+| --- | --- |
+| [core-concepts-and-rules.md](./core-concepts-and-rules.md) | Fast operating reference for planes, guardrails, role boundaries, execution lifecycle, research memory, and documentation rules. |
+| [product-direction.md](./product-direction.md) | Product thesis, target user posture, goals, non-goals, product language, default runtime, universe scope, and open-core posture. |
+| [harness.md](./harness.md) | Top-level harness model: roles, skills, service-layer state, policy, MCP, research memory, approvals, execution adapters, audit, and improvement loops. |
+| [components.md](./components.md) | Component-first maintenance registry, taxonomy tags, owned surfaces, dependencies, capabilities, and validation. |
+
+## Workflow And Agent Documents
+
+| Document | Owns |
+| --- | --- |
+| [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. |
+| [artifact-supervisor-loop-prd.md](./artifact-supervisor-loop-prd.md) | Artifact Supervisor Loop PRD, bounded follow-up routing, lane escalation, loop state, and Decision Quality Spine preservation. |
+
+## Safety And Improvement Documents
+
+| Document | Owns |
+| --- | --- |
+| [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. |
+
+## Implementation And Operations Documents
+
+| Document | Owns |
+| --- | --- |
+| [system-architecture.md](./system-architecture.md) | Django modular monolith, central DB ownership, app boundaries, runtime planes, service-layer use cases, and core models. |
+| [interfaces-and-surfaces.md](./interfaces-and-surfaces.md) | Product web, Django Admin, Django Ninja API, MCP boundary, CLI, generated wrapper behavior, and external MCP surface. |
+| [generated-workspaces.md](./generated-workspaces.md) | `tcx attach`, `tcx init`, `tcx update`, generated files, project-scoped MCP config, hooks, workspace provenance, profile scope, and template rules. |
+| [validation-and-test-plan.md](./validation-and-test-plan.md) | Required validation commands, unit/API/generator/smoke coverage, MCP smokes, broker provider smokes, routing scenarios, and release-sensitive checks. |
+| [deployment.md](./deployment.md) | PyPI/TestPyPI release process, CI/CD, Trusted Publishing, installer/update policy, versioning, and what is not deployed. |
+| [licensing-and-commercialization.md](./licensing-and-commercialization.md) | Apache-2.0 open-core boundary, generated workspace ownership, contributions, trademark posture, and legal review needs. |
+
+## Change-To-Docs Map
+
+| Change type | Update these docs |
+| --- | --- |
+| Product scope, non-goals, default runtime, product language, or release posture | `product-direction.md`, `core-concepts-and-rules.md` |
+| Top-level harness model, component registry, guardrail/improvement taxonomy, or cross-cutting concept language | `harness.md`, `components.md`, `guardrails.md`, `improvement-loop.md`, `core-concepts-and-rules.md` |
+| User-facing workflow intake, suitability/profile context, plain-English output, or professional finance framing | `financial-workflow-references.md`, `interfaces-and-surfaces.md`, `roles-skills-and-workflows.md` |
+| Role roster, head-manager dispatch, skills, strategy behavior, routing, information barriers, or handoff quality | `roles-skills-and-workflows.md`, `artifact-supervisor-loop-prd.md`, `core-concepts-and-rules.md` |
+| Research memory, source snapshots, forecast ledgers, readiness labels, artifact paths, report quality, or markdown preview | `research-memory-and-artifacts.md`, `improvement-loop.md`, `artifact-supervisor-loop-prd.md` |
+| Policy, permissions, approvals, idempotency, execution, adapters, broker safety, external MCP gate, or secret handling | `safety-policy-and-execution.md`, `guardrails.md`, `core-concepts-and-rules.md` |
+| Django apps, models, service-layer contracts, central DB ownership, or runtime topology | `system-architecture.md` |
+| Product web, Admin, REST, MCP, CLI, or generated wrapper behavior | `interfaces-and-surfaces.md` |
+| Workspace templates, bootstrap, hooks, project MCP config, generated files, or update behavior | `generated-workspaces.md` |
+| Test expectations, smoke flows, validation commands, or regression scenarios | `validation-and-test-plan.md` |
+| Packaging, installer, release automation, versioning, or distribution boundary | `deployment.md`, `installation.md` |
+| License, contribution, trademark, generated workspace ownership, or commercialization boundary | `licensing-and-commercialization.md` |
+
+## Source-Of-Truth Principles
+
+| Principle | Meaning |
+| --- | --- |
+| Docs first for product behavior | Durable rules for safety, roles, workflows, execution, generated workspaces, and release posture belong in these docs. |
+| Update docs with behavior | Code, templates, prompts, hooks, tests, and generated artifacts that change durable behavior should update the owning doc in the same change. |
+| Keep `README.md` concise | The public README should explain the product and route readers here instead of duplicating every rule. |
+| Keep OpenWiki agent-focused | `openwiki/` should help agents work efficiently and link back to these docs for durable explanations. |
+| Keep product language English | TradingCodex product copy, generated workspace guidance, Admin UI, CLI help, role prompts, durable docs, and examples are written in English unless a reviewed localization layer is being built. |
+| Product web is review-first | The `/` web app opens on workflow planning and can preview handoffs; it does not spawn agents, approve orders, or execute orders. |
+| Open-core boundary is explicit | Apache-2.0 covers the repository open core; trademarks and official commercial offerings remain separately governed. |

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/deployment.md

@@ -141,7 +141,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.2.9
+  tradingcodex==0.2.10
 rm -rf /tmp/tcx-testpypi-smoke
 mkdir -p /tmp/tcx-testpypi-smoke
 cd /tmp/tcx-testpypi-smoke
@@ -170,7 +170,7 @@ After the PyPI workflow completes:
 
 ```bash
 python3.11 -m venv /tmp/tcx-pypi
-/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.9
+/tmp/tcx-pypi/bin/pip install tradingcodex==0.2.10
 rm -rf /tmp/tcx-pypi-smoke
 mkdir -p /tmp/tcx-pypi-smoke
 cd /tmp/tcx-pypi-smoke
@@ -263,7 +263,8 @@ Use PEP 440 versions:
   loop state after `0.2.7`
 - `0.2.9` for stale service replacement and web scroll-state fixes after
   `0.2.8`
-- later patch releases for compatible fixes after `0.2.9`
+- `0.2.10` for workflow planning and automation skill updates after `0.2.9`
+- later patch releases for compatible fixes after `0.2.10`
 - pre-releases such as `0.3.0a1`, `0.3.0b1`, or `0.3.0rc1` when preparing
   the next minor contract
 

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/financial-workflow-references.md

@@ -42,12 +42,12 @@ drafting, approval, or execution.
 | [Markowitz, "Portfolio Selection" (1952)](https://ideas.repec.org/a/bla/jfinan/v7y1952i1p77-91.html) | Portfolio roles should treat expected return, variance, covariance, and diversification as analytical lenses, not as automatic trade instructions. |
 | [Fama and French, "Common risk factors in the returns on stocks and bonds" (1993)](https://ideas.repec.org/a/eee/jfinec/v33y1993i1p3-56.html) | Research and portfolio outputs should separate issuer-specific thesis claims from factor, market, maturity, and default-risk exposure. |
 | [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) | Agentic finance workflows need visible governance, context mapping, measurement, and risk-management checkpoints. |
-| [NIST AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) | Prompt gates, handoff states, quality checks, and audit outputs should map to govern, map, measure, and manage functions. |
+| [NIST AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) | Workflow intake, handoff states, quality checks, and audit outputs should map to govern, map, measure, and manage functions. |
 | [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. |
-| [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 prompt gates, fixed subagents, MCP/service boundaries, artifacts, and generated workspace state. |
+| [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. |
 | [Anthropic Claude Code hooks docs](https://docs.anthropic.com/en/docs/claude-code/hooks-guide) | Agent hooks can verify conditions before allowing a workflow to continue; TradingCodex maps this to hook gates, context-audit, quality-check, and handoff states. |
@@ -140,7 +140,7 @@ strategy authoring path, not as a side effect of analysis.
 - Recent loop-engineering frameworks converge on recurring agent triggers,
   reusable procedures, subagent decomposition, verification hooks, connectors,
   and durable memory. TradingCodex should stay framework-agnostic: use these
-  ideas through its own Codex-native prompt gates, skills, MCP/service boundary,
+  ideas through its own Codex-native workflow intake, skills, MCP/service boundary,
   context-audit, role artifacts, and explicit human approval gates.
 - The verifier is the bottleneck in a useful loop. TradingCodex therefore keeps
   loop controls tied to source freshness, artifact quality, profile gaps, and

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/generated-workspaces.md

@@ -99,7 +99,9 @@ Generated workspaces contain:
 - 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
 - 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
-- closed selected team: hook/starter-prompt selected roles are binding for the current lane; research-only prompts do not add portfolio, risk, approval, or execution roles for precautionary coverage
+- validated staged workflow plan: hook intake hints are not binding; `$tcx-workflow`
+  drafts, validates, records, and dispatches from a staged plan before
+  substantive investment analysis
 - negated scope routing: phrases such as "no valuation", "no order", and "no trading" remove those actions or roles from dispatch selection
 - broad public-equity prompts such as "Analyze NVDA" default to deep thesis
   review with fundamental, technical, news, and valuation roles unless explicit
@@ -114,7 +116,7 @@ Generated workspaces contain:
   before opening full markdown; `reader_summary` and `next_action` keep the
   first-read experience clear for non-expert users
 - context-budget audit: `./tcx subagents context-audit --strict` inspects the
-  latest prompt gate, prompt-gate history, compact hook context, subagent
+  latest workflow intake, intake history, compact hook context, subagent
   session state, workflow loop state, and research artifacts after long multi-subagent runs; it
   fails strict mode when handoff artifacts lack `context_summary`, compact gate
   history grows beyond budget, or gate/state/history payloads look like pasted
@@ -126,9 +128,9 @@ Generated workspaces contain:
 - compact workflow loop state: `.tradingcodex/mainagent/workflow-loop-state.json`
   is the latest summary and pointer; the canonical state for each routed prompt
   lives under `.tradingcodex/mainagent/workflows/<workflow_run_id>/loop-state.json`
-  with the matching prompt gate beside it. The state records selected team,
-  allowed follow-up team, escalation-only roles, loop policy, pending tasks,
-  planner decisions, escalation proposals, blocked actions, and stop reason
+  with `intake.json` and `workflow-plan.json` beside it. The state records
+  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
 - Codex session/thread routing map:
   `.tradingcodex/mainagent/session-workflow-runs.json` maps a Codex app session
@@ -138,7 +140,7 @@ Generated workspaces contain:
 - fixed subagent `nickname_candidates` set to a single item matching the exact role `name`
 - fixed subagent identities kept in `.codex/agents/*.toml` `developer_instructions`, as required by Codex custom agent files
 - project-local additional agent instructions under `.tradingcodex/agent-instructions/<role>.md`; projection appends them after generated default instructions for `head-manager` and fixed subagents
-- twenty-three core repo skills across project-scope mainagent skills and subagent skill directories, each with `SKILL.md` frontmatter for document metadata and `agents/openai.yaml` UI metadata
+- twenty-five core repo skills across project-scope mainagent skills and subagent skill directories, each with `SKILL.md` frontmatter for document metadata and `agents/openai.yaml` UI metadata
 - shared decision-quality skill bundles for forecasting discipline, thesis
   scenario trees, numeric data QC, and anti-overfit validation
 - standalone `strategy-*` skills under `.agents/skills/strategy-*` for user-approved agent-readable investment strategies, created through `strategy-creator`, CLI, API, or service-layer flows and exposed to the root `head-manager` through the strategy marker block in `.codex/config.toml`; Django web lists and previews them read-only
@@ -387,17 +389,15 @@ enforcement.
 
 - prompt classification
 - secret warnings
-- natural-language investment workflow auto-routing context
+- natural-language investment workflow intake context and deterministic hints
 - direct-answer prevention context
 - duplicate marker management
-- prompt-gate audit metadata with prompt hash and workflow lane, without raw
+- workflow-intake audit metadata with prompt hash and heuristic lane, without raw
   prompt text in the audit ledger
-- compact hook `additionalContext`; the full generated starter prompt remains
-  in `.tradingcodex/mainagent/latest-user-prompt-gate.json` and is loaded only
-  when the compact gate is insufficient
-- compact Artifact Supervisor Loop metadata in hook context for
-  `allowed_followup_team`, `escalation_team`, `loop_policy`, the latest loop
-  summary, and the canonical run-specific loop-state path
+- compact hook `additionalContext`; full staged workflow contracts are recorded
+  by `$tcx-workflow` under `.tradingcodex/mainagent/workflows/<workflow_run_id>/`
+- compact Artifact Supervisor Loop metadata in recorded `workflow-plan.json`
+  and `loop-state.json`, not as final hook-selected teams
 - assisted loop planner previews through `./tcx subagents loop --artifact
   <path>`, with optional `--record` limited to file-native pending tasks,
   planner decisions, escalation proposals, blocked actions, and stop reason

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/harness.md

@@ -54,7 +54,7 @@ TradingCodex Harness
 | Provenance | Record which workspace and role produced or requested work without making workspaces separate ledgers. |
 | Profiles | Separate paper portfolio/account/strategy state from workspace identity. |
 | Components | Provide the developer-facing maintenance map for implementation surfaces, dependencies, capabilities, tags, and validation. |
-| Context efficiency | Keep subagent briefs compact, pass artifact paths and context summaries before full artifacts, audit long runs with `subagents context-audit` over prompt-gate history, and avoid repeated role manuals or source dumps. |
+| Context efficiency | Keep subagent briefs compact, pass artifact paths and context summaries before full artifacts, audit long runs with `subagents context-audit` over workflow intake history, and avoid repeated role manuals or source dumps. |
 | Responsibility boundaries | Keep role identity, MCP allowlists, permission profiles, hooks, policies, skills, schemas, and service behavior in their own authoritative surfaces. |
 
 ## Components As Maintenance Units
@@ -106,8 +106,8 @@ It is a tag and review lens applied to components.
 - Context efficiency keeps those quality gates usable by passing summaries and
   artifact references first, then opening full evidence only when needed.
 - Context-budget audits make long multi-subagent runs inspectable by checking
-  compact hook context, prompt-gate history, starter prompt size, bounded
-  subagent session state, and `context_summary` coverage across research
+  compact hook intake, intake history, bounded subagent session state,
+  workflow loop state, and `context_summary` coverage across research
   artifacts. Full subagent event history stays in append-only audit JSONL.
 
 Improvement does not authorize execution. A high-quality report still needs the
@@ -120,12 +120,14 @@ Quality Spine remains the cross-lane quality contract inside that loop. Neither
 the loop nor the spine widens role authority, MCP access, approval, execution,
 broker, or secret boundaries.
 
-Runtime loop inspection is file-native and read-first. Hooks write canonical
-per-run state under
-`.tradingcodex/mainagent/workflows/<workflow_run_id>/loop-state.json` and a
-compact latest summary at `.tradingcodex/mainagent/workflow-loop-state.json`;
-`tcx subagents plan` shows the current selected team, allowed follow-up team,
-escalation-only roles, pending tasks, stop reason, and canonical state path.
+Runtime loop inspection is file-native and read-first. `$plan-workflow`
+clarifies ambiguous requests into a compact mandate; `UserPromptSubmit`
+writes compact intake; `$tcx-workflow` records the validated staged plan and
+canonical per-run state under
+`.tradingcodex/mainagent/workflows/<workflow_run_id>/`. A compact latest
+summary stays at `.tradingcodex/mainagent/workflow-loop-state.json`;
+`tcx subagents plan` shows the current staged plan, selected team, pending
+tasks, stop reason, and canonical state path.
 Codex session/thread ids are mapped through
 `.tradingcodex/mainagent/session-workflow-runs.json`, so multiple Codex app
 threads in the same workspace can continue different loops without overwriting

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/interfaces-and-surfaces.md

@@ -203,7 +203,9 @@ Django Ninja provides local/staff typed control APIs:
 - `GET|PATCH|DELETE /api/subagents/{role}/optional-skills/{name}`
 - `POST /api/subagents/{role}/optional-skills/{name}/activate|archive`
 - `GET /api/workflows/{id}`
-- `POST /api/workflows/{id}/validate`
+- `POST /api/workflows/intake` records compact workflow intake hints without raw prompt storage
+- `POST /api/workflows/{id}/validate` validates an agent-authored staged workflow plan, or returns a deterministic preview for compatibility
+- `POST /api/workflows/record` records a validated staged workflow plan and initializes loop state
 - `POST /api/policy/simulate`
 - `GET|POST /api/orders/tickets`; list responses are scoped to the active
   profile (`portfolio_id`, `account_id`, `strategy_id`)
@@ -395,8 +397,8 @@ provider, then registration stores only provider metadata and `credential_ref`.
 - `./tcx research create|append|get|list|search|export`
 
 Default main-agent skill listing is user-facing, not exhaustive. It shows only
-direct user entrypoints: `tcx-workflow`, `tcx-server`, `tcx-build`,
-`strategy-creator`, `postmortem`, and active `strategy-*` skills. Full
+direct user entrypoints: `plan-workflow`, `tcx-workflow`, `automate-workflow`,
+`tcx-server`, `tcx-build`, `strategy-creator`, `postmortem`, and active `strategy-*` skills. Full
 inspection is available through
 `./tcx skills list --all` and role-specific `./tcx subagents skills <role>`.
 

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/roles-skills-and-workflows.md

@@ -98,23 +98,26 @@ they are not required before `head-manager` routes the work.
 
 | Trigger | Handling |
 | --- | --- |
-| General investment request, such as "Analyze Apple stock" | `UserPromptSubmit` injects compact auto-dispatch context with lane, selected team, blocked actions, and the persisted prompt-gate path; `head-manager` dispatches or reuses selected subagents before analysis. |
-| Explicit `$tcx-workflow` request | The workflow skill becomes the primary manual-control orchestrator and dispatches selected subagents. |
+| Ambiguous planning request, such as "help me design a workflow for daily market prep" | Route through `$plan-workflow`; ask focused questions, preserve negated scope, and produce a compact workflow mandate before execution or automation. |
+| General investment request, such as "Analyze Apple stock" | `UserPromptSubmit` records compact workflow intake hints; `head-manager` uses `$tcx-workflow` to draft, validate, record, and then dispatch from a staged workflow plan before analysis. |
+| Explicit `$tcx-workflow` request | The workflow skill becomes the primary orchestrator, records a validated staged plan, and dispatches selected stages. |
+| Recurring automation request, such as "run this before market open every day" | Route through `$automate-workflow`; use `$plan-workflow` first when the recurring mandate is ambiguous or execution-sensitive, then register an active Codex automation only after the mandate is armed. |
 | Broker/provider build request, such as "connect this broker" | Route to the `connector_build` lane and `$tcx-build`; connect/scaffold/register/validate provider metadata without investment dispatch or live submission. |
 | Runtime/server request, such as "open dashboard" or "check TradingCodex status" | Route to `$tcx-server`; report service/MCP/update posture and use CLI recovery commands without changing execution authority. |
-| Explicit subagent/parallel/delegated request | `UserPromptSubmit` records the explicit activation source; the skill checks existing subagent state before creating/reusing sessions. |
+| Explicit subagent/parallel/delegated request | `UserPromptSubmit` records intake hints; the skill checks existing subagent state and validates the staged plan before creating/reusing sessions. |
 | Strategy authoring request, such as "Create a quality income strategy" | Do not auto-dispatch investment subagents. Route through `strategy-creator`, CLI, API, or service-layer flows so the strategy skill is created and projected as a root/head-manager strategy entry. Django web previews strategies read-only. |
 | Non-investment repository, docs, or harness administration request | No investment dispatch is required; `head-manager` follows normal Codex coding-agent behavior while preserving execution and secret guardrails. |
 | Same run/role subagent is active | Wait or follow up instead of creating duplicates. |
 | Same role artifact has passed quality gates | Reuse the artifact instead of duplicating work. |
 | Codex `spawn_agent` schema cannot select exact fixed role | Treat role routing as `routing-unverified`; provide `waiting_for_subagent_dispatch` and task briefs only. |
 
-The selected role team from compact hook context or the persisted starter
-prompt is binding for the current lane. `head-manager` must not add roles
-outside that team merely because they might be useful. For `research_only`, do
-not add valuation, portfolio, risk, approval, or execution roles unless the
-user later asks for valuation, decision support, portfolio fit, sizing, order
-drafting, approval, or execution.
+Hook-selected roles are deterministic hints, not the final contract. The
+recorded validated staged workflow plan is binding for the current run.
+`head-manager` must not add roles outside that plan merely because they might
+be useful. For `research_only`, do not add valuation, portfolio, risk,
+approval, or execution roles unless the user later asks for valuation,
+decision support, portfolio fit, sizing, order drafting, approval, or
+execution and a new validated plan permits it.
 
 Negated scope terms are binding. Phrases such as "no valuation", "no order", or
 "no trading" remove those actions or roles from routing instead of triggering
@@ -175,7 +178,7 @@ Instruction/skill separation:
 | Surface | Owns | Must not own |
 | --- | --- | --- |
 | `head-manager` base instructions | durable identity, safety invariants, dispatch fail-closed rule, role boundaries, approved action boundary, skill routing | workflow templates, scenario tables, long checklists, subagent message bodies |
-| Head-manager skills | compact repeatable procedures for workflow routing, server/runtime recovery, build-mode work, strategy creation, and postmortems | role identity, durable routing authority, MCP allowlists, weakening base guardrails, bypassing role-owned skills, approving or executing directly |
+| Head-manager skills | compact repeatable procedures for workflow planning, workflow routing, automation arming, server/runtime recovery, build-mode work, strategy creation, and postmortems | role identity, durable routing authority, MCP allowlists, weakening base guardrails, bypassing role-owned skills, approving or executing directly |
 | Fixed subagent TOML | standing role identity, role purpose, artifact wall, model/tool config, MCP allowlist, single-item display nickname candidates, and always-on prohibitions | per-request user intent, workflow lane decisions, source selection, or temporary task-specific context |
 | Role-owned skills | capability procedure, artifact expectations, quality checks, and local output rules | role eligibility, work for other roles, self-approval, execution outside MCP |
 | Main-to-subagent briefs | request-specific assignment envelope: verbatim user request, explicit constraints, workflow consent posture, research artifact language, lane, artifact path, `context_summary`, data-cutoff needs, request-specific out-of-scope items, and return contract | standing role manuals, model/tool config, MCP allowlists, long method checklists, long source-class lists, full artifacts, or repeated guardrail prose |
@@ -206,7 +209,9 @@ role work directly.
 User-visible skill lists are not the same as enabled or installed skills. The
 main-agent user surface should show only direct user entrypoints by default:
 
+- `plan-workflow`
 - `tcx-workflow`
+- `automate-workflow`
 - `tcx-server`
 - `tcx-build`
 - `strategy-creator`
@@ -238,7 +243,9 @@ Head-manager skill responsibilities:
 
 | Skill | Responsibility |
 | --- | --- |
+| `plan-workflow` | focused user Q&A, ambiguity detection, negated-scope preservation, and user-language compact workflow mandate creation before immediate or recurring workflows |
 | `tcx-workflow` | compact workflow routing, selected-team dispatch/reuse, Artifact Supervisor Loop planning, handoff quality states, bounded follow-up/escalation proposals, and synthesis after accepted artifacts |
+| `automate-workflow` | mandate reuse from `$plan-workflow`, preflight checks, arming status, user-language automation summaries, and Codex automation registration for recurring TradingCodex workflows without granting execution authority |
 | `tcx-server` | startup health, local dashboard URL guidance, explicit user-requested dashboard opening, Codex restart guidance, TradingCodex MCP setup, update-status explanation, read-only broker/status inspection, and service troubleshooting without granting execution authority |
 | `tcx-build` | full-access plus TCX-build-mode gated self-update, template/harness edits, broker/API provider connect/scaffold/register/validate flows, credential-ref handling, and live-submit blocking outside service gates |
 | `external-data-source-gate` | read-only external evidence-source constraints and External MCP Gate honesty |
@@ -353,13 +360,11 @@ posture, or core skill behavior.
   summary with total counters and a recent-event window. Full subagent event
   history belongs in `trading/audit/subagent-session-events.jsonl`.
 - `.tradingcodex/mainagent/workflow-loop-state.json` is the compact latest
-  assisted-loop summary and pointer. The canonical loop state for a routed
-  prompt lives under
-  `.tradingcodex/mainagent/workflows/<workflow_run_id>/loop-state.json`, with
-  the matching prompt gate beside it. It contains selected team, allowed
-  follow-up team, escalation-only roles, pending tasks, planner decisions,
-  blocked actions, and stop reason. It is inspectable state, not an automatic
-  recursive dispatch mechanism.
+  assisted-loop summary and pointer. The canonical run folder contains
+  `intake.json`, `workflow-plan.json`, and `loop-state.json`. It contains
+  validated stages, selected team, allowed follow-up team, pending tasks,
+  planner decisions, blocked actions, and stop reason. It is inspectable
+  state, not an automatic recursive dispatch mechanism.
 - `.tradingcodex/mainagent/session-workflow-runs.json` maps Codex session or
   thread keys to workflow run ids. Subagent start/stop records use run id,
   role, and subagent session id so a reused role session can continue the right
@@ -371,6 +376,7 @@ posture, or core skill behavior.
 - Downstream roles start from artifact path plus `context_summary`; they open
   full markdown only for disputed, stale, missing, or load-bearing evidence.
 - The head-manager should tell subagents to write reader-facing research artifacts in the user's language from the original request unless the user explicitly requests another artifact language. File paths, frontmatter keys, symbols, tickers, source names, and quoted source text stay in their natural/original form.
+- `plan-workflow` mandates and `automate-workflow` automation summaries follow the same user-language rule.
 - When selecting an exact fixed role with Codex `spawn_agent`, do not combine `agent_type` with full-history forking. Use a compact assignment envelope on the first attempt and no model/reasoning overrides.
 - Workflow consent stays separate from explicit user constraints. Consent to orchestrate or use subagents allows dispatch, but it is not itself an analytical constraint.
 - Execution roles may additionally receive the approved action boundary because they need it to submit approved actions.
@@ -398,7 +404,7 @@ TradingCodex MCP allowlists, and service-layer policy.
 
 ## Hooks Are Guidance
 
-- `UserPromptSubmit` handles prompt classification, secret warnings, direct-answer prevention context, and duplicate marker management.
+- `UserPromptSubmit` handles prompt classification, secret warnings, compact workflow intake hints, direct-answer prevention context, and duplicate marker management. It does not choose the final staged workflow plan.
 - `SessionStart` writes compact TradingCodex mode, permission, update, server/MCP, and routing diagnostics for `head-manager`; incompatible service details such as version mismatch, DB mismatch, and occupied ports must survive into compact context so `head-manager` can mention the startup notice before claiming dashboard readiness. Startup recovery and dashboard URL guidance stay in `$tcx-server`, while self-update and connector implementation stay in `$tcx-build`.
 - Official `UserPromptSubmit` matchers are ignored, so classification happens inside the hook script.
 - Hooks use command type only and do not rely on ordering or concurrency between hooks.

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/docs/validation-and-test-plan.md

@@ -85,7 +85,7 @@ Smoke coverage should verify:
 - generated workspace contains `.tradingcodex/workspace.json`
 - generated workspace contains `.tradingcodex/generated/component-index.json`
 - generated workspace contains no `package.json` or Node MCP/runtime files
-- generated workspace contains nine fixed subagents and twenty-three core repo skills
+- generated workspace contains nine fixed subagents and twenty-five core repo skills
 - two generated workspaces have different workspace ids
 - two generated workspaces keep separate research markdown/source-snapshot files while sharing non-research MCP ledger rows through the central DB
 - profile selection controls paper portfolio separation
@@ -233,14 +233,14 @@ Scenarios should include:
   answered, and complete active-profile investor context
 - starter-prompt web profile-answer forms persist answers to the active profile
   and the refreshed preview removes those questions
-- Codex `UserPromptSubmit` generated hooks reuse answered active-profile
-  investor context in the persisted starter prompt while keeping compact
-  `additionalContext` under budget
+- Codex `UserPromptSubmit` generated hooks keep compact intake hints under
+  budget; `$tcx-workflow` reuses answered active-profile investor context when
+  drafting the validated staged plan
 - unavailable or unverified subagent routing fails closed
 - completed role artifacts are reused when quality gates pass
 - downstream roles return `revise`, `blocked`, or `waiting` instead of filling missing upstream role work
-- hook `additionalContext` stays compact and points to the persisted prompt gate
-  instead of injecting the full starter prompt into every routed turn
+- hook `additionalContext` stays compact and points to persisted workflow
+  intake instead of injecting a full starter prompt into every routed turn
 - starter prompts and generated guidance expose the no-overlap handoff contract
 - starter prompts and generated guidance tell subagents to write reader-facing
   research artifacts in the user's language unless explicitly overridden
@@ -255,13 +255,12 @@ Scenarios should include:
   budget so agents pass artifact paths, context summaries, source snapshot IDs,
   and short deltas instead of full artifacts or repeated role manuals
 - multi-round subagent smokes run `tcx subagents context-audit --strict` after
-  several prompt gates, subagent start/stop events, and large research
+  several workflow intakes, subagent start/stop events, and large research
   artifacts across research-only, thesis, portfolio/risk, order-draft,
   approval/execution, crypto, ETF/index, and options/instrument lanes; the
-  audit must show compact hook context, bounded starter prompts, compact prompt
-  gate history, compact session state with total counters plus retained recent
-  events, no pasted markdown artifacts in
-  gate/history/state, no research artifacts missing `context_summary`, and
+  audit must show compact hook intake, compact intake history, compact session
+  state with total counters plus retained recent events, no pasted markdown artifacts in
+  intake/history/state, no research artifacts missing `context_summary`, and
   warnings for artifacts missing reader-first `reader_summary` or `next_action`
 - repo skill boundary tests fail when role identifiers leak into generic skills
   outside necessary command principal examples or policy/artifact contracts

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tradingcodex"
-version = "0.2.9"
+version = "0.2.10"
 description = "Codex-native trading harness with a Django service plane and approved action boundary."
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{tradingcodex-0.2.9 → tradingcodex-0.2.10}/tests/test_e2e_user_scenarios.py

@@ -78,7 +78,7 @@ def test_generated_workspace_connects_mock_broker(tmp_path: Path) -> None:
     tcx(workspace, env_extra, "mode", "set", "build", "--reason", "mock broker connector smoke")
     gate = hook_context(workspace, "Connect mock-json broker. No order, no trading, do not read secrets.", env_extra)
     assert gate is not None
-    assert gate["workflow_lane"] == "connector_build"
+    assert gate["heuristic_lane"] == "connector_build"
 
     write_mock_provider(
         workspace,
@@ -218,24 +218,16 @@ def test_generated_workspace_codex_cli_user_scenario_matrix(tmp_path: Path) -> N
     for index, (prompt, lane, roles, secret_warning) in enumerate(prompt_cases):
         gate = hook_context(workspace, prompt, env_extra, via_hooks_json=index == 0)
         assert gate is not None, prompt
-        assert gate["workflow_lane"] == lane
-        assert gate["required_subagents"] == roles
+        assert gate["heuristic_lane"] == lane
+        assert gate["heuristic_roles"] == roles
         assert gate["secret_warning"] is secret_warning
-        assert gate["confirmation_required"] is False
-        assert gate["context_mode"] == "compact_workflow_gate"
-        assert gate["starter_prompt_path"] == ".tradingcodex/mainagent/latest-user-prompt-gate.json"
+        assert gate["intake_path"].endswith("/intake.json")
         assert "starter_prompt" not in gate
         assert len(json.dumps(gate, ensure_ascii=False)) < 1800
-        if roles:
-            persisted_gate = json.loads((workspace / ".tradingcodex" / "mainagent" / "latest-user-prompt-gate.json").read_text(encoding="utf-8"))
-            starter = persisted_gate["starter_prompt"]
-            assert "This selected team is binding for the current lane" in starter
-            assert "Research artifact language:" in starter
-            assert "Use handoff states: accepted, revise, blocked, waiting." in starter
-            assert "source/as-of posture" in starter
-            assert "Context budget:" in starter
-            assert "context_summary" in starter
-            assert "Blocked actions before artifacts:" in starter
+        persisted_intake = json.loads((workspace / ".tradingcodex" / "mainagent" / "latest-workflow-intake.json").read_text(encoding="utf-8"))
+        assert persisted_intake["heuristic_lane"] == lane
+        assert "prompt_sha256" in persisted_intake
+        assert prompt not in json.dumps(persisted_intake, ensure_ascii=False)
 
     hook_audit_path = workspace / "trading" / "audit" / "codex-hooks.jsonl"
     assert hook_audit_path.exists()
@@ -251,7 +243,7 @@ def test_generated_workspace_codex_cli_user_scenario_matrix(tmp_path: Path) -> N
     status = json.loads(tcx(workspace, env_extra, "subagents", "status").stdout)
     assert status["installed_count"] == 9
     assert status["fixed_roster_ok"] is True
-    assert status["skills_installed"] == 23
+    assert status["skills_installed"] == 25
     plan = json.loads(tcx(workspace, env_extra, "subagents", "plan", "--all").stdout)
     assert plan["requested_count"] == 9
     assert plan["parallel_spawn_ok"] is True
@@ -476,16 +468,15 @@ def test_long_multi_subagent_context_budget_audit(tmp_path: Path) -> None:
     for round_index, (prompt, expected_lane) in enumerate(scenarios, start=1):
         context = hook_context(workspace, prompt, env_extra)
         assert context is not None
-        assert context["workflow_lane"] == expected_lane
+        assert context["heuristic_lane"] == expected_lane
         assert "starter_prompt" not in context
         assert len(json.dumps(context, ensure_ascii=False)) < 1600
 
-        persisted_gate = (workspace / ".tradingcodex" / "mainagent" / "latest-user-prompt-gate.json").read_text(encoding="utf-8")
-        assert sentinel not in persisted_gate
-        assert "Context budget:" in persisted_gate
-        assert "context_summary" in persisted_gate
+        persisted_intake = (workspace / ".tradingcodex" / "mainagent" / "latest-workflow-intake.json").read_text(encoding="utf-8")
+        assert sentinel not in persisted_intake
+        assert "prompt_sha256" in persisted_intake
 
-        for role in context["required_subagents"]:
+        for role in context["heuristic_roles"]:
             artifact_id = f"long-{round_index}-{role}"
             hook_event(workspace, "subagent-start", {"agent_type": role, "task_name": f"{role} round {round_index}"}, env_extra)
             markdown = (