From a2b42316394b4dc0192932fff793f08fd9f30b2b Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Thu, 28 May 2026 23:18:43 +0800
Subject: [PATCH] Document research repository boundary

---
 README.md            | 37 +++++++++++++++++++++++++++++++++++++
 docs/architecture.md | 21 ++++++++++++++++++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 836571f..97d5108 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,24 @@ allocation policy. It prepares and validates shadow signal artifacts that can
 later be consumed by sidecar plugins after a separate review and promotion
 process.
 
+## Repository Role
+
+This is a research artifact repository, not an agent runner, model gateway,
+execution service, or strategy plugin repository.
+
+Its job is to keep point-in-time research evidence reproducible:
+
+- build current-market context bundles
+- create dated GitHub Issues for operator review
+- store schema-valid shadow AI signal artifacts
+- preserve `signal_history` for future walk-forward replay
+- provide deterministic replay tooling around saved artifacts
+
+`CodexAuditBridge` remains the only bridge/runner for model providers and
+cross-repository write automation. Future live or notification behavior belongs
+in a separate deterministic plugin after the shadow artifacts have enough
+evidence.
+
 ## Boundary
 
 This repo owns:
@@ -25,6 +43,25 @@ This repo does not own:
 - deterministic strategy rules in `UsEquityStrategies`
 - runtime plugin execution in `QuantStrategyPlugins`
 - API keys for model providers
+- Codex/OpenAI/Anthropic provider routing
+- GitHub App token minting for source repository writes
+- Telegram or broker-facing runtime notifications
+
+## Current Status
+
+This repository is in shadow research accumulation mode. The first saved
+point-in-time artifact is `data/output/signal_history/2026-05-28.json`.
+
+Near-term work should focus on:
+
+- keeping the weekly workflow healthy
+- accumulating saved `signal_history/*.json` artifacts
+- replaying only saved artifacts, not regenerated historical AI judgments
+- improving context quality before any downstream plugin integration
+
+Do not promote the output into runtime allocation or notifications until the
+saved artifact history has enough walk-forward evidence to justify a separate
+plugin contract.
 
 ## Operating Model
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 42a76d9..13b1f95 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -6,6 +6,11 @@ QuantStrategyLab already separates strategy math, snapshot generation, runtime
 execution, and broker adapters. This repository adds a research-only AI signal
 pipeline without changing that production boundary.
 
+This repository is deliberately narrower than `CodexAuditBridge`. It owns
+research inputs, validation, saved artifacts, and replay harnesses. It does not
+own model provider routing, API keys, GitHub App write orchestration, live
+notifications, or execution behavior.
+
 ## Main Design Pressure
 
 LLM output is not naturally deterministic or backtestable. The repository must
@@ -15,7 +20,7 @@ order routing.
 ## Recommended Low-Risk Shape
 
 - `AiLongHorizonSignalPipelines` stores context examples, schema, validation,
-  and shadow artifacts.
+  replay tooling, and shadow artifacts.
 - `CodexAuditBridge` owns provider routing and API keys.
 - GitHub Issues are the first operator notification layer for scheduled shadow
   signal runs.
@@ -25,6 +30,18 @@ order routing.
 - `QuantStrategyPlugins` may later read promoted artifacts as sidecar context.
 - Platform repositories remain unchanged.
 
+## Lifecycle
+
+The current lifecycle is accumulation-first:
+
+1. Build a point-in-time context bundle.
+2. Ask `CodexAuditBridge` to review it and produce a shadow-only artifact when
+   evidence is sufficient.
+3. Save both `latest_signal.json` and dated `signal_history/YYYY-MM-DD.json`.
+4. Replay only saved artifacts against later prices.
+5. Consider a deterministic plugin only after enough walk-forward evidence
+   exists.
+
 ## Not Recommended
 
 - Giving AI broker credentials.
@@ -35,6 +52,8 @@ order routing.
   artifacts.
 - Sending runtime Telegram or broker-facing notifications directly from this
   research repository before a deterministic plugin contract exists.
+- Duplicating `CodexAuditBridge` provider fallback or cross-repository write
+  logic inside this repository.
 
 ## Validation Strategy