feat: add local QuantOS kernel and Codex broker

Add immutable E0 research runs, point-in-time baseline validation, bounded local Codex review, truthful legacy web contracts, and deterministic release gates.

Co-Authored-By: Codex <noreply@openai.com>

Author: Oscar

.gitattributes

@@ -0,0 +1,10 @@
+* text=auto
+*.csv text eol=lf
+*.json text eol=lf
+*.jsonl text eol=lf
+*.md text eol=lf
+*.py text eol=lf
+*.js text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

.github/workflows/python-ci.yml

@@ -17,11 +17,14 @@ jobs:
       - run: python -m pip install --upgrade pip
       - run: pip install -e ".[full]"
       - run: pytest -q
-      - run: python scripts/qrae_run_full_v0.py --cycle-id ci_full_cycle
+      - name: Run and verify deterministic kernel fixture
+        shell: bash
+        run: |
+          run_output="$(python -m qrae.cli run --work-order examples/price_baseline/work_order.json --workspace . --output-root .quantos-ci)"
+          run_dir="$(python -c 'import json,sys; print(json.load(sys.stdin)["run_dir"])' <<<"$run_output")"
+          python -m qrae.cli verify --run-dir "$run_dir"
       - run: python scripts/qrae_readiness.py --env dev
       - uses: actions/upload-artifact@v4
         with:
           name: qrae-v0-artifacts
-          path: |
-            research_base/latest/*
-            reports/generated/*
+          path: .quantos-ci/

.gitignore

@@ -0,0 +1,22 @@
+.quantos/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.env
+.env.*
+!.env.example
+/data/
+reports/generated/
+*.pem
+*.key
+*.pfx
+*.p12
+auth.json

AI_RESUME.md

@@ -6,6 +6,23 @@
 
 ---
 
+## 0. Authoritative rebaseline — 2026-07-11
+
+This section supersedes older implementation-status, Vercel-first, cron, and next-sprint claims elsewhere in this historical handoff. Verify every capability against current files and tests.
+
+- The product is now **local-first QuantOS**. Vercel is a legacy/deferred sanitized review surface, not the scheduler, storage truth, quant engine, or authority.
+- The current source release candidate is `0.10.0`; the live Vercel surface remains on the older `0.9.x` deployment until a verified deployment replaces it.
+- A real deterministic kernel exists in `src/qrae/`: strict work orders, immutable artifacts, hash-chained state, point-in-time price quality, a next-observation after-cost baseline, independent recomputation, evidence/claim/decision/report/knowledge artifacts, and a bounded optional local Codex broker.
+- The example fixture and the generic V0 price contract are capped at `E0`. `E1` remains blocked until authenticated data provenance and a registered market adapter exist; no current code produces WFO, event replay, paper, live, or allocator-ready evidence.
+- The current source disables public web cron execution and removes Vercel schedules. The live deployment was still serving the older `202 accepted` contract when checked on 2026-07-11; treat it as stale and do not infer that it executes work.
+- Codex runs only through an explicit local, shell-free, read-only, schema-bound broker. It starts no listener, receives no trading/cloud-write credential, and cannot promote research state. Disabled/unavailable Codex becomes `DEFERRED_NO_CODEX` while deterministic work continues.
+- A local end-to-end broker smoke on 2026-07-11 produced a validated `DRAFT_READY` adversarial critique with `requested_transition=NONE`; this proves the installed Codex CLI boundary, not research quality or deployment readiness.
+- `configs/qrae_requirements_traceability.json` was downgraded to evidence-backed statuses and is enforced by `python scripts/qrae_traceability_audit.py --strict`.
+- Current executable commands are documented in `README.md` and `docs/LOCAL_KERNEL.md`; older quick-start commands naming missing scripts are obsolete.
+- The broad QuantOS remains incomplete. Next implementation gates are real read-only market adapters across registered families, durable local catalog/brain, WFO/statistical/risk modules, event replay for survivors, report factory, and only later optional online adapters/review UI.
+
+---
+
 ## 1. Project identity
 
 **Project name:** QRAE-RD  

README.md

@@ -1,120 +1,89 @@
-# QRAE-RD V0
+# QRAE QuantOS
 
-**QRAE-RD** = **Quant Research Agent Engine — Research Director Architecture**.
+QRAE is a local-first, human-gated quantitative research operating system. The repository now contains a real deterministic kernel slice alongside the older staging dashboard.
 
-Current implementation tag: **V0.9.0 / official V0 full-cycle staging candidate**.
+## Current truth
 
-This repository is the official V0 scaffold for the CUHK QTS autonomous, human-gated, agent-orchestrated quantitative research pipeline.
+Implemented and tested:
 
-## Resume here first
+- strict, hash-bound research work orders;
+- point-in-time CSV price contracts and data-quality quarantine;
+- a delayed-fill lagged-momentum baseline with registered entry/liquidation costs and chronological train/validation/test splits;
+- immutable run bundles, atomic latest pointers, and tamper-evident state logs;
+- metric/accounting recomputation, evidence ceilings, claim ledgers, decision records, compact reports, and knowledge records;
+- an optional local Codex broker with fixed tasks, an isolated read-only permission profile, bounded output, no state-promotion authority, and deterministic no-Codex fallback;
+- legacy read-only Vercel dashboard/API views; deployment content may lag this branch and is not execution evidence.
 
-Future AIs and engineers should begin with:
+Not yet implemented: production market adapters, remote storage/batch adapters, walk-forward and nested model selection, event-driven replay, portfolio/risk engines, ML challengers, a complete Obsidian brain, allocator-grade report generation, authenticated web review, or any paper/live execution system.
 
-- [`AI_RESUME.md`](AI_RESUME.md) — canonical project handoff containing the user’s requirements, ideas, architecture decisions, safety rules, deployment state, trial outcomes, unresolved gaps, and exact next actions.
+The committed dashboard artifacts and legacy synthetic tournament are demonstrations, not evidence that those missing systems ran.
 
-The system is designed around one rule:
+## Local quick start
 
 ```text
-Scripts search and verify.
-Cheap/free AI drafts and implements routine tasks.
-Strong AI acts as Research Director only for survivors.
-Human approves only important decisions.
+python -m pip install -e ".[full]"
+python -m pytest -q
+python -m qrae.cli run --work-order examples/price_baseline/work_order.json --workspace . --output-root .quantos
 ```
 
-## What this repo contains
-
-- RD-Agent-style specification/synthesis/implementation/validation/analysis loop.
-- Multi-asset opportunity tournament: Polymarket, crypto, ETFs, bonds, equities, macro.
-- Deterministic quant truth engine: data validation, backtests, walk-forward, risk, scores.
-- RD-Agent-compatible score vector: IC, ICIR, Rank IC, Rank ICIR, ARR, IR, MDD, Calmar.
-- QRAE extended score vector: OOS Sharpe, WFE, Sortino, Omega, VaR/CVaR, turnover, data quality, overfit penalty.
-- Human-gated Research Director packet flow for ChatGPT Plus/Pro or Gemini CLI, plus a deterministic V0 Research Director surrogate so the no-API pipeline can run end-to-end.
-- Vercel/GitHub-ready static dashboard, serverless APIs, cron contracts, notification hooks, MCP placeholders.
-- Allocator-style report template and CUHK QTS paper plan.
-
-## V0 operating mode
-
-V0 is intentionally **no-paid-API-first**:
+The command prints the immutable run directory. Verify it independently:
 
 ```text
-Vercel/GitHub run automation.
-The deterministic Research Director surrogate can run automatically for V0 end-to-end validation.
-ChatGPT Plus is still the preferred high-quality reviewer for top packets when human review is desired.
-Gemini CLI can be used locally for low-cost implementation tasks.
-API automation can be added later through the Research Director adapter.
+python -m qrae.cli verify --run-dir .quantos/runs/<run-id>
 ```
 
-No live trading is enabled in V0.
-
-## Quick start
-
-```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[full]"
-pytest -q
-python scripts/qrae_readiness.py --env dev
-python scripts/qrae_run_cycle.py --cycle-id local_cycle
-python scripts/qrae_run_full_v0.py --cycle-id local_full_cycle
-python scripts/qrae_smoke.py --pytest
-python scripts/run_demo.py
-python scripts/qrae_task_pack.py --example
-npm ci
-npm run typecheck
-npm run build
-```
+The bundled dataset is synthetic and its work order is capped at `E0`. It proves mechanics and artifact integrity only.
 
-The deterministic cycle creates ranked idea cards, a latest digest, and a Research Director packet.
+## Local Codex review
 
-## V0 dev/prod posture
+Codex is optional and never owns metrics or state transitions. Prepare a fixed review task from a verified run:
 
-Use the included readiness checker before promotion:
+```text
+python -m qrae.cli codex-prepare --run-dir .quantos/runs/<run-id> --task-id critic-001 --task-kind ADVERSARIAL_CRITIC
+```
 
-```bash
-python scripts/qrae_readiness.py --env dev
-python scripts/qrae_readiness.py --env staging
-python scripts/qrae_readiness.py --env prod
+Without an explicit enable flag, execution records a safe `DEFERRED_NO_CODEX` result:
+
+```text
+python -m qrae.cli codex-run --work-order .quantos/codex-work-orders/<run-id>/critic-001.json --workspace .quantos
 ```
 
-`dev` is expected to pass without external services. `staging` is designed to pass without external paid services for V0 preview validation. `prod` intentionally requires database/artifact/notification configuration before it passes. Live trading and automated LLM execution remain disabled in V0.
+To invoke the locally authenticated Codex CLI, repeat with `--enable-codex`. The broker uses a fixed `codex exec` argument vector, hash-checked stdin evidence, an isolated read-only permission profile, disabled action tools/integrations, ignored user config/rules, a strict output schema, streaming time/output bounds, a sanitized environment, and an immutable outbox. It starts no listener and receives no trading or cloud-write credentials.
 
-## Recommended GitHub/Vercel setup
+## Architecture posture
 
-1. Push this repository as the initial commit.
-2. Import the repo into Vercel.
-3. Use `Other` framework preset, `npm ci`, `npm run build`, output `public`.
-4. Add `QRAE_ENVIRONMENT=staging` and `QRAE_DISABLE_AUTOMATED_LLM=true`.
-5. Add Postgres/Neon, Blob/S3/R2, and Resend later for production.
-6. Connect GitHub to ChatGPT for repo reading.
-7. Add QRAE MCP connector later for dashboard/artifact access inside ChatGPT.
+- Canonical research state, private alpha, artifacts, and decisions are local.
+- Optional online services may later fetch, store, or batch-process bounded data through hash-verified adapters.
+- Vercel is a deferred sanitized review surface, not the scheduler, database, quant engine, or authority.
+- Research code has no live-order path. Paper, shadow, and live execution require a separate approved OMS/risk/reconciliation system.
+- Data and deterministic artifacts own facts; validators own hard gates; humans own publication, exceptional risk, and capital.
 
-## Human workflow
+## Repository map
 
 ```text
-1. Configure research universes and schedules.
-2. Let daily/weekly workflows generate ideas, backtests, WFO, risk, scores.
-3. Receive Gmail notification only when candidates survive.
-4. Copy Research Director packet into ChatGPT Plus/Pro.
-5. Paste the decision back into QRAE.
-6. System queues deepen/revise/reject/report action.
+src/qrae/                    deterministic contracts, kernel, state, artifacts, baseline, Codex broker
+tests/                       positive and negative deterministic tests
+examples/price_baseline/     synthetic E0 work order and price fixture
+scripts/qrae_run_cycle.py    compatibility wrapper for the local kernel
+api/ and public/             legacy read-only Vercel review surface
+configs/                     legacy runtime, quality, and traceability configuration
+research_base/latest/        committed legacy demonstration artifacts
 ```
 
-## Docs
+## Documentation
 
-- [`AI_RESUME.md`](AI_RESUME.md)
+- [`docs/LOCAL_KERNEL.md`](docs/LOCAL_KERNEL.md)
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
-- [`docs/RESEARCH_METHODOLOGY.md`](docs/RESEARCH_METHODOLOGY.md)
 - [`docs/QUALITY_GATES.md`](docs/QUALITY_GATES.md)
 - [`docs/REQUIREMENTS_TRACEABILITY.md`](docs/REQUIREMENTS_TRACEABILITY.md)
-- [`docs/CUHK_QTS_PAPER_PLAN.md`](docs/CUHK_QTS_PAPER_PLAN.md)
-- [`AGENTS.md`](AGENTS.md)
-- [`PROJECT_CONTEXT.md`](PROJECT_CONTEXT.md)
+- [`AI_RESUME.md`](AI_RESUME.md) — historical handoff; verify claims against files and tests.
 
 ## Safety status
 
 ```yaml
+local_canonical_state: true
 live_trading: false
-automated_paid_llm: false
-source_of_truth: deterministic_artifacts
+public_codex_endpoint: false
+codex_state_promotion: false
 human_capital_gate_required: true
 ```

api/_qrae.js

@@ -13,17 +13,17 @@ function readJson(relativePath, fallback) {
 }
 
 const runtimeConfig = readJson('configs/qrae_runtime.json', {});
-const VERSION = runtimeConfig.version || '0.9.0';
+const VERSION = runtimeConfig.version || '0.10.0';
 const GENERATED_AT = '2026-07-05T00:00:00.000Z';
 
 const qraeRuntime = {
   system: 'QRAE-RD',
   version: VERSION,
-  mode: runtimeConfig.mode || 'v0.9-human-gated-plus-deterministic-director-surrogate',
+  mode: runtimeConfig.mode || 'v0.10-local-first-e0-kernel',
   environment: process.env.QRAE_ENVIRONMENT || process.env.VERCEL_ENV || 'local',
   liveTradingEnabled: false,
-  automatedLlmEnabled: process.env.QRAE_DISABLE_AUTOMATED_LLM !== 'false' ? false : true,
-  directorMode: process.env.QRAE_DISABLE_AUTOMATED_LLM === 'false' ? (runtimeConfig.directorModeWhenAutomated || 'api-adapter-optional') : (runtimeConfig.directorModeWhenManual || 'manual-chatgpt-plus-or-deterministic-surrogate'),
+  automatedLlmEnabled: false,
+  directorMode: runtimeConfig.directorModeWhenManual || 'optional-local-codex-cli',
   sourceOfTruth: 'deterministic-artifacts-not-llm-text',
 };
 
@@ -51,7 +51,7 @@ const qraeScoreVector = [
 const dashboardCards = runtimeConfig.dashboardCards || [
   { title: 'Health', href: '/api/health', body: 'Runtime and safety state.' },
   { title: 'Research status', href: '/api/research/status', body: 'Enabled universes, integrations, and V0 governance.' },
-  { title: 'Latest digest', href: '/api/research/latest', body: 'Latest research digest contract for dashboards and ChatGPT packets.' },
+  { title: 'Legacy digest', href: '/api/research/latest', body: 'Committed review snapshot with no freshness guarantee.' },
 ];
 
 function json(res, payload, status = 200) {

api/cron/daily-research.js

@@ -2,17 +2,11 @@ const { json, methodGuard, basePayload } = require('../_qrae');
 module.exports = function handler(req, res) {
   if (!methodGuard(req, res)) return;
   json(res, basePayload({
-    status: 'accepted',
+    status: 'disabled',
     workflow: 'daily-research',
-    mode: 'v0-python-worker-contract',
-    trigger: 'cron-or-manual',
-    actions: [
-      'refresh latest data adapters',
-      'run data-quality gates',
-      'generate/score idea cards',
-      'auto-reject weak candidates',
-      'write artifacts for survivor packets',
-    ],
-    nextStep: 'Run scripts/qrae_run_cycle.py in the worker/CI environment for deterministic artifact generation.',
-  }), 202);
+    mode: 'local-only-disabled',
+    actions: [],
+    reason: 'Public web scheduling is disabled. Run the verified local QuantOS CLI; this endpoint cannot queue or execute research.',
+    liveTradingEnabled: false,
+  }), 410);
 };

api/cron/weekly-director-packet.js

@@ -2,15 +2,11 @@ const { json, methodGuard, basePayload } = require('../_qrae');
 module.exports = function handler(req, res) {
   if (!methodGuard(req, res)) return;
   json(res, basePayload({
-    status: 'accepted',
+    status: 'disabled',
     workflow: 'weekly-director-packet',
-    mode: 'manual-research-director-gate',
-    actions: [
-      'compile survivor candidates',
-      'build Research Director packet',
-      'notify Gmail/Resend when configured',
-      'wait for human/strong-model decision',
-    ],
+    mode: 'local-only-disabled',
+    actions: [],
+    reason: 'Public web scheduling is disabled. Prepare and review packets through the local QuantOS CLI.',
     liveTradingEnabled: false,
-  }), 202);
+  }), 410);
 };

api/director/latest.js

@@ -7,6 +7,6 @@ module.exports = function handler(req, res) {
     decisionAvailable: Boolean(decision),
     decision,
     markdown,
-    note: 'This is the deterministic Research Director surrogate output. Treat as a plan; metrics remain artifact-grounded.',
+    note: 'Committed legacy demonstration only; it is not a current local-kernel decision or freshness proof.',
   }));
 };

api/health.js

@@ -1,5 +1,10 @@
 const { json, methodGuard, basePayload, safetyRules } = require('./_qrae');
 module.exports = function handler(req, res) {
   if (!methodGuard(req, res)) return;
-  json(res, basePayload({ status: 'ok', safetyRules }));
+  json(res, basePayload({
+    status: 'legacy_review_surface',
+    canonicalState: 'local',
+    publicResearchExecutionEnabled: false,
+    safetyRules,
+  }));
 };