From fd7c19ba058456419a165532020804c32dbbc605 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Wed, 7 Oct 2026 02:02:36 +0800
Subject: [PATCH] docs: lead README with human-readable intro, add governance
 files

Move the QSL architecture role checklist in README.md/README.zh-CN.md
after the plain-language description instead of before it, and add
CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md, which were
missing from this repository.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 CODE_OF_CONDUCT.md | 16 ++++++++++++++++
 CONTRIBUTING.md    | 28 ++++++++++++++++++++++++++++
 README.md          |  3 +--
 README.zh-CN.md    |  3 +--
 SECURITY.md        | 22 ++++++++++++++++++++++
 5 files changed, 68 insertions(+), 4 deletions(-)
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..40aa8e6
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,16 @@
+# Code of Conduct
+
+## Our Standards
+
+- Be respectful, direct, and evidence-oriented in issues, pull requests, reviews, and discussions.
+- Assume technical disagreement is about the work. Keep feedback specific to code, docs, data, evidence, reproducibility, or operational risk.
+- Avoid harassment, insults, discriminatory language, personal attacks, and repeated off-topic comments.
+- Do not pressure maintainers or contributors to disclose private account details, credentials, trading records, unpublished data, or personal information.
+
+## Project Scope
+
+This repository builds artifact-first market signal sources for QuantStrategyLab strategy platforms: it reads market data, computes deterministic derived indicators, and publishes hash-pinned signal bundles and contracts for downstream consumers. Contributions should keep claims about signal quality and coverage conservative and verifiable, separate research evidence from runtime/platform guarantees, and avoid presenting indicator outputs as investment advice. Discussions touching provider data licensing, artifact provenance, or downstream platform consumption should stay measured, reproducible, and evidence-based rather than speculative.
+
+## Reporting and Enforcement
+
+Report conduct concerns to the maintainer on GitHub: `@Pigbibi`. Maintainers may edit or remove comments, close issues or pull requests, restrict participation, or take other reasonable steps to protect contributors and project integrity.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..04e2cfe
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for contributing to `MarketSignalSources`.
+
+## Ground Rules
+
+- Prefer small, low-risk pull requests.
+- Keep refactors separate from behavior changes.
+- Add or update tests when changing runtime behavior.
+- Do not use deployment or scheduled workflows as a substitute for local verification.
+- This repository only produces signal artifacts and contract validators; it does not submit orders, hold broker credentials, or mutate platform runtime settings. Changes that would add any of those belong in a different repository.
+- Keep artifact schemas (`market_signal_bundle.v1`, `market_signal_quality_report.v1`, `market_signal_consumer_contracts.v1`, and related manifests) backward compatible, or call out the break explicitly and update all affected validators in the same pull request.
+
+## Branching and Pull Requests
+
+- Create a topic branch for each change.
+- Open a pull request with a short summary and a concrete test plan.
+- Wait for CI to pass before merging.
+
+## Local Verification
+
+Run the main verification commands before opening a pull request:
+
+```bash
+python -m pip install -e . pytest 'ruff==0.15.22' build
+ruff check .
+python -m pytest tests -q
+```
diff --git a/README.md b/README.md
index 8823acd..0f6e7b4 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 # MarketSignalSources
 
+Artifact-first market signal source builders for QuantStrategyLab strategy platforms.
 
 ## QSL architecture role
 
@@ -9,8 +10,6 @@
 - **Consumes**: public/market inputs and downstream strategy consumers.
 - **Must not**: submit orders or mutate platform runtime settings.
 
-Artifact-first market signal source builders for QuantStrategyLab strategy platforms.
-
 ## Installation
 
 This package is intended to be consumed directly from GitHub by strategy and
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 54fe061..576693a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,5 +1,6 @@
 # MarketSignalSources
 
+QuantStrategyLab 策略平台的市场信号源构建工具包，采用 artifact-first 设计。
 
 ## QSL 架构角色
 
@@ -9,8 +10,6 @@
 - **消费对象**：公开/市场输入和下游策略消费者。
 - **禁止事项**：下单或修改平台 runtime settings。
 
-QuantStrategyLab 策略平台的市场信号源构建工具包，采用 artifact-first 设计。
-
 ## 安装
 
 ```bash
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..9565fd9
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,22 @@
+# Security Policy
+
+Thanks for helping keep `MarketSignalSources` safe.
+
+This repository builds and publishes market signal artifacts consumed by QuantStrategyLab strategy and platform repositories. It does not hold broker credentials or submit orders, but published artifacts and manifests can still affect what downstream platforms inject into live strategies. Please do **not** open a public issue for vulnerabilities involving provider credentials, artifact integrity (e.g. a way to forge or tamper with a signal bundle's hash/provenance so it passes validation), or secret material.
+
+## Reporting a Vulnerability
+
+- Contact the maintainer directly at GitHub: `@Pigbibi`.
+- Include the repository name, affected commit or branch, environment details, and exact reproduction steps.
+
+## Secret and Credential Exposure
+
+If you suspect provider API keys, tokens, or other credentials were exposed in this repository (for example in a committed artifact, fixture, or log):
+
+1. Rotate the exposed secrets immediately.
+2. Pause any scheduled publication job that depends on the exposed credential.
+3. Share only the minimum evidence needed to reproduce the issue.
+
+## Scope Notes
+
+Security fixes should stay minimal and focused. Please avoid bundling unrelated refactors with a security report or patch.