LLMQuant · keli-wen · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026
diff --git a/.claude/rules/contexts-authoring.md b/.claude/rules/contexts-authoring.md
@@ -0,0 +1,17 @@
+---
+paths:
+  - "contexts/**/*.md"
+---
+
+# Contexts authoring standard
+
+You are editing a page under `contexts/`. Follow the QuantMind contexts authoring standard. `tests/test_contexts.py` (run inside `scripts/verify.sh`) enforces the structural rules below, so a page that ignores them fails the build — getting them right up front avoids a red verify.
+
+Load-bearing rules:
+
+- Open every `contexts/**/*.md` with `## Quick Summary`, then `## Contents`, in that order, both within the first 80 lines.
+- The `## Contents` links must exactly match the page's `##` section headings (GitHub-style anchors: lowercase, punctuation stripped, spaces and hyphens collapsed to one hyphen).
+- Register the page in its index and keep index links resolving: a design page in `contexts/design/README.md`, a dev route in `contexts/dev/README.md`.
+- Do not hard-wrap prose to a fixed width. Keep each paragraph and list item on one physical line; tables, fenced code, and mermaid keep their own line structure.
+
+Canonical source (read it before a non-trivial contexts change): `.claude/skills/quantmind-dev/references/write-contexts.md`. Run `bash scripts/verify.sh` before pushing a contexts change.
diff --git a/.claude/settings.json b/.claude/settings.json
@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PROJECT_DIR}/scripts/hooks/pre_tool_use_no_bypass.py\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.codex/hooks.json b/.codex/hooks.json
@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$(git rev-parse --show-toplevel)/scripts/hooks/pre_tool_use_no_bypass.py\"",
+            "timeout": 10,
+            "statusMessage": "Checking for --no-verify bypass"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -18,6 +18,11 @@ repos:
 
 -   repo: local
     hooks:
+    -   id: commit-msg-format
+        name: Enforce English Conventional Commit subject
+        entry: python3 scripts/hooks/commit_msg_check.py
+        language: system
+        stages: [commit-msg] # Runs against the commit message file.
     -   id: verify
         name: Run scripts/verify.sh (deterministic verification harness)
         entry: bash scripts/verify.sh

diff --git a/AGENTS.md b/AGENTS.md
@@ -1,10 +1,12 @@
 # QuantMind — Agent Instructions
 
-Guidance for coding agents contributing to this repository. Keep this file
-aligned with `CLAUDE.md` (same core rules); update both in the same change.
+Guidance for coding agents contributing to this repository. This file is the
+single source of repository instructions; `CLAUDE.md` imports it verbatim, so
+edit rules here, not there.
 
-Use [`contexts/README.md`](contexts/README.md) as the repository information
-entry point for either development or library-usage work.
+Start at [`contexts/CONTEXT_MAP.md`](contexts/CONTEXT_MAP.md), the navigation
+index for `contexts/`. [`contexts/README.md`](contexts/README.md) is the
+routing entry point for development or library-usage work.
 
 ## Progressive Context Loading
 
@@ -142,7 +144,7 @@ A new feature ships with a unit test **and** a focused example:
 For commit, pull-request, or component-implementation tasks, load the
 `quantmind-dev` skill and follow the matching reference:
 
-- `.agents/skills/quantmind-dev/SKILL.md` (this toolchain)
+- `.agents/skills/quantmind-dev/SKILL.md` (Codex and other AGENTS.md-based tools)
 - `.claude/skills/quantmind-dev/SKILL.md` (Claude Code)
 
 The two copies are identical; when changing the skill, update both in the

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,150 +1,8 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working in
-this repository. Keep this file aligned with `AGENTS.md` (same core rules);
-update both in the same change.
-
-Use [`contexts/README.md`](contexts/README.md) as the repository information
-entry point for either development or library-usage work.
-
-## Progressive Context Loading
-
-Pages under `contexts/` are agent-facing references designed for progressive
-disclosure:
-
-1. Read lines 1-80 first. The preview contains `Quick Summary` and `Contents`
-   sections that explain the page's purpose, authority, and scope.
-2. Use that preview to decide whether the page applies. Do not preload sibling
-   pages or follow unrelated links.
-3. When a page applies, read the entire page before changing code, contracts,
-   or repository guidance. The preview routes work; it does not replace the
-   detailed contract.
-4. Follow directly linked canonical sources only as the task requires. Avoid
-   deep reference chains and duplicate guidance in working context.
-
-## What This Is
-
-QuantMind is a knowledge extraction and retrieval library for quantitative
-finance, built **on top of** the OpenAI Agents SDK. It is a domain library,
-not an agent framework: runtime, tracing, tool scaffolding, and multi-agent
-handoff all come from `openai-agents`.
-
-## Module Map
-
-| Module | Role |
-|--------|------|
-| `quantmind/knowledge/` | Pydantic data standard (`FlattenKnowledge` / `TreeKnowledge` / `GraphKnowledge`) — dependency leaf |
-| `quantmind/library/` | Local persistence and semantic retrieval for canonical knowledge — depends only on `knowledge` |
-| `quantmind/configs/` | Operation cfg + typed input models or unions (`BaseFlowCfg`, `NewsWindow`, `PaperInput`) — depends only on `knowledge` |
-| `quantmind/preprocess/` | Deterministic fetch / format / clean / time utilities — depends only on `utils` |
-| `quantmind/rag/` | Opinionated LlamaIndex document chunking and retrieval — depends only on `preprocess` |
-| `quantmind/flows/` | Apex layer: public library operations (`paper_flow`, `collect_news`, `batch_run`) |
-| `quantmind/magic.py` | `resolve_magic_input`: natural language → `(input, cfg)` |
-| `quantmind/mind/` | Pure-agentic reasoning layer — memory + agentic (reasoning-based) retrieval where an LLM decides; mechanical retrieval (similarity / BM25) lives in `rag` / `library` |
-| `quantmind/utils/` | Logger only — keep it that way |
-
-The pre-migration agent runtime was removed and archived on the
-`archive/agent-runtime-final` branch. Reference it for history; never
-resurrect it into master.
-
-## Setup and Verification
-
-```bash
-uv venv && source .venv/bin/activate
-uv pip install -e ".[dev]"
-bash scripts/verify.sh              # deterministic required verification
-```
-
-`scripts/verify.sh` runs five fast-fail steps (`ruff format --check`,
-`ruff check`, `basedpyright`, `lint-imports`, `pytest --cov`) and must remain
-network-free. `.github/workflows/ci.yml` is the required deterministic CI
-workflow. Public-network integrations have separate bounded smoke tests;
-`.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered
-component jobs. Run each applicable smoke test when changing that component
-and before publishing. External service availability must not block changes
-outside that component. `docs/README.md` is the single catalog of component
-commands; do not enumerate them in this file.
-
-To extend live verification, add a component-specific
-`scripts/verify_<component>_e2e.py`, add a named job to the existing `e2e.yml`,
-extend its precise PR path filter, and add one catalog row. When a second live
-job is added, use GitHub-native per-job change detection so PRs run only the
-affected component jobs. Do not add another E2E workflow, a generic runner or
-registry, or a base E2E class. Do not bypass pre-commit / pre-push hooks unless
-the user explicitly authorizes it — fix the underlying issue instead.
-
-## Architecture Constraints (stable)
-
-1. **Library, not framework** — use functions for self-contained stateless
-   transformations and small service classes that bind, at construction, the
-   immutable `cfg`/policy/dependency that must stay constant across calls; the
-   runtime operand is passed per call. Binding `cfg` for batch reproducibility
-   alone justifies a class (`PaperFlow(cfg).build(input)`,
-   `AgenticRetriever(cfg).retrieve(structure, q)`), and the cfg *type* may select the
-   shape/strategy (typed dispatch, not a class hierarchy). Keep canonical values
-   free of runtime service state; use `Protocol` over ABC, with no
-   framework-style class hierarchies, plugin registries, hook discovery, or CLI.
-2. **RAG data plane, not framework** — use LlamaIndex directly inside
-   `quantmind.rag`; keep upstream types private and do not add retriever,
-   vector-store, provider, or backend registries.
-3. **Do not rebuild the agent runtime** — use `openai-agents` directly; no
-   QuantMind-side facades over `from agents import ...`.
-4. **Schema models vs runtime evidence** — user/LLM inputs and configs use
-   extra-forbid Pydantic models; knowledge adds `frozen=True`; deterministic
-   fetch, preprocessing, and collection values use frozen dataclasses when
-   they do not need validation or JSON Schema (`Fetched`, `NewsBatch`).
-5. **Import boundaries are contracts** — `import-linter` (configured in
-   `pyproject.toml`) pins the dependency graph; never work around a failing
-   contract.
-6. **Absolute imports** across module boundaries.
-7. **No meaningless wrappers** — a method must add logic, abstraction, or a
-   side effect beyond the call it wraps; otherwise inline it.
-8. **Name public operations by intent** — follow
-   `contexts/design/operations/naming.md`; use stage verbs, and reserve
-   `pipeline` for deliberate multi-stage composition. `flow` as a verb or
-   `*_flow` function name is banned; `Flow` as a noun on a document handle
-   (`PaperFlow`) is allowed.
-9. **Pipelines produce self-contained artifacts** — a `flows` pipeline is pure
-   processing (`input → artifact`) and returns a value usable *and storable*
-   without a store; it does not bind a `library`, persist, or retrieve.
-   `library` only dumps and loads (`put(artifact)` / `open_*`, round-tripping to
-   an identical value); `mind` only retrieves, returning evidence **values**
-   (content included) with any locator as optional provenance. A self-contained
-   artifact carries its own text (and any embeddings) plus the minimal
-   provenance metadata (`as_of` + a light source ref) needed to persist and
-   time-query it standalone — never a reference refilled from a store. Keep that
-   provenance metadata out of the artifact's `id` / `content_hash` (identity
-   stays reproducible); share it via a light provenance base, not full
-   `BaseKnowledge`. Accept modest redundancy to keep artifacts self-contained.
-   Half-finished intermediates stay component seams, not public flows. See
-   `contexts/design/operations/orchestration.md`.
-
-## Tests and Examples
-
-A new feature ships with a unit test **and** a focused example:
-
-- Tests: `tests/<module>/`, subclass `unittest.TestCase`, mock external
-  services, cover success and failure paths.
-- Examples: `examples/<module>/`, one simple usage per file.
-- Public operations and sources: update the catalog in `docs/README.md` and
-  follow the `quantmind-dev` component checklist.
-
-## Communication
-
-- Commit messages: English, Conventional Commits.
-- PR titles, PR bodies, and issue bodies: English.
-- GitHub Issue, Pull Request, Discussion, and comment body formatting follows
-  the [GitHub writing style](contexts/dev/github-writing.md); never hard-wrap
-  remote prose at 80 columns or another fixed width.
-- Code comments and docstrings: English, Google style.
-
-## Development Workflows
-
-For commit, pull-request, or component-implementation tasks, load the
-`quantmind-dev` skill and follow the matching reference:
-
-- `.claude/skills/quantmind-dev/SKILL.md` (Claude Code)
-- `.agents/skills/quantmind-dev/SKILL.md` (other agent toolchains)
-
-The two copies are identical; when changing the skill, update both in the
-same change.
+<!--
+CLAUDE.md imports AGENTS.md as the single source of repository instructions for
+coding agents. Do not duplicate rules here — edit AGENTS.md. Add Claude Code-
+specific guidance (if any) below the import. This block-level HTML comment is
+stripped from Claude's context at load, so it costs no tokens.
+-->
+
+@AGENTS.md
diff --git a/contexts/CONTEXT_MAP.md b/contexts/CONTEXT_MAP.md
@@ -0,0 +1,54 @@
+# Context Map
+
+## Quick Summary
+
+- **Purpose**: The navigation index for `contexts/`. Before reading or writing anything under `contexts/`, start here to find the one page a task needs.
+- **Read when**: Beginning any repository, design, or library-usage task, or adding a new `contexts/` page (register it in the map below and in its area index).
+- **Load next**: Pick the single route in [Where to Start](#where-to-start); then open only that page and follow its `Load next` line.
+- **Status**: Current. `AGENTS.md` (imported by `CLAUDE.md`) points here as the first read for `contexts/` work.
+
+## Contents
+
+- [Directory Map](#directory-map)
+- [Where to Start](#where-to-start)
+
+## Directory Map
+
+```
+contexts/
+├── CONTEXT_MAP.md              ← you are here: the navigation index
+├── README.md                   ← routing entry point (dev / usage / design)
+├── design/                     ← accepted design decisions and planned behavior
+│   ├── README.md               ← design index
+│   ├── flow/
+│   │   ├── paper.md            ← source-first Paper Flow V1
+│   │   └── news.md             ← news collection design and behavior
+│   ├── knowledge/paper.md      ← Paper source and artifact models
+│   ├── library/local.md        ← LocalKnowledgeLibrary storage and retrieval
+│   ├── mind/retrieval.md       ← page-preserving structure tree + agentic retrieval
+│   ├── operations/
+│   │   ├── naming.md           ← public operation naming rules
+│   │   └── orchestration.md    ← pipelines vs components (altitude)
+│   ├── preprocess/pdf.md       ← page-aware ParsedDocument
+│   ├── rag/document.md         ← deterministic chunking + BM25
+│   └── utils/
+│       ├── structured_output.md ← structured-output contract
+│       └── usage.md            ← per-run token / time / step usage
+├── dev/                        ← contributor and agent development rules
+│   ├── README.md               ← dev rule index
+│   ├── labels.md               ← issue / PR label taxonomy
+│   ├── github-writing.md       ← GitHub prose style (no hard-wrap)
+│   └── harness-engineering.md  ← enforcement layers, hooks, rules, alignment
+└── usage/
+    └── README.md               ← using QuantMind as a library
+```
+
+## Where to Start
+
+| I want to | Open |
+|---|---|
+| Understand the whole `contexts/` layout | the [Directory Map](#directory-map) above |
+| Develop, fix, test, or review code | [`dev/README.md`](dev/README.md) |
+| Use QuantMind as a library | [`usage/README.md`](usage/README.md) |
+| Read or change a design decision | [`design/README.md`](design/README.md) |
+| Add a hook, rule, or CI gate | [`dev/harness-engineering.md`](dev/harness-engineering.md) |
diff --git a/contexts/README.md b/contexts/README.md
@@ -14,7 +14,7 @@
 
 ## Routes
 
-This directory is the public repository context system for coding agents and maintainers. Start with the index that matches the work you are doing:
+This directory is the public repository context system for coding agents and maintainers. For a full page-by-page navigation index, see [`CONTEXT_MAP.md`](CONTEXT_MAP.md). Start with the index that matches the work you are doing:
 
 - [Develop QuantMind](dev/README.md) for architecture, contribution, testing, and verification guidance.
 - [Use QuantMind](usage/README.md) for public operations, examples, and usage documentation.

diff --git a/contexts/dev/README.md b/contexts/dev/README.md
@@ -21,6 +21,7 @@ Use this index when extending or maintaining the repository. Follow the linked r
 | Package responsibilities and coding rules | [`AGENTS.md`](../../AGENTS.md) or [`CLAUDE.md`](../../CLAUDE.md) |
 | Component-development workflow | [`quantmind-dev` component workflow](../../.agents/skills/quantmind-dev/references/develop-components.md) |
 | Issue and pull-request labels | [Repository label guidance](labels.md) |
+| Enforcement layers, hooks, rules, and Claude/Codex alignment | [Harness engineering](harness-engineering.md) |
 | Issue and pull-request body formatting | [GitHub writing style](github-writing.md) |
 | Public operation and source catalog | [`docs/README.md`](../../docs/README.md) |
 | Public operation naming | [Operation naming rules](../design/operations/naming.md) |