quant-finance-practice-and-theory

Imported from zcoderz/quant-finance-practice-and-theory (AGENTS.md). Install upstream with npx skills add zcoderz/quant-finance-practice-and-theory. Copyright stays with the author.

StochasticCalculus — Agent Instructions (Self‑Learning Book, Preserve Depth)

This repo is a quantitative finance / stochastic calculus curriculum written as Markdown chapters under chapters/, with exercises and worked solutions under solutions/.

Mission

• Improve correctness, clarity, and self-study usability without losing the existing high-quality depth.
• Preserve long, intuition-building explanations; make them easier to navigate (add “Fast Path” summaries + better structure), not shorter by default.
• Keep changes incremental and reviewable; avoid large rewrites and unnecessary churn.
• Work slowly and carefully: think deeply before editing, preserve prior intent, and only make changes that are clearly higher quality than what they replace.

Source of truth for the improvement project

• Project plan: notes/IMPROVEMENT_PLAN.md
• Phase checklists: notes/PHASES.md and notes/phases/
• What’s done vs next: notes/PROGRESS.md
• Per-chapter status: notes/CHAPTER_TRACKER.md
• Cross-chapter conventions/policies: notes/DECISIONS.md
• Baseline snapshot: notes/BASELINE_2026-02-02.md

If you do work that affects tracking, update the relevant notes/ files in the same PR/patch.

Repo layout (high-level)

• chapters/ — main book content (33 chapters + outline + glossary)
• solutions/ — worked solutions (many chapters have multi-part solution files)
• templates/ — style guide and writing templates
• scripts/ — maintenance tools (links/anchors/TOC/anchors normalization)
• knowledge_base/ — concept registry/graph (used for consistency)
• notes/ — improvement project management (plan + tracking)

Style and writing rules

Follow the repo’s style guide unless the user requests otherwise:

• templates/STYLE_GUIDE.md

Key rules:

• Keep the existing voice (technical but approachable; interview-ready and production-aware).
• Do not delete “long intuition” sections; instead:
  • add a short Fast Path summary (5–10 bullets),
  • keep the Deep Dive section and improve signposting/subheadings,
  • add sanity checks/pitfalls to prevent common misunderstandings.
• Avoid changing anchors/headers unless necessary; if you must, update all inbound links.

Evidence-first policy (MCP books server)

For non-trivial claims (theorems, conditions, conventions, algorithm steps, “desk reality” practices):

1. Collect evidence first using MCP books_rag:
   • answer(query, alpha=0.3, rerank=true, limit=8) (start here)
   • search_structured(...) to target specific formulations
   • fetch_chunk(uuid) for full context
   • verify_draft(text, support_threshold=3.0, max_sentences=30) after drafting
2. Draft only what you can support.
3. If unclear or sources conflict, keep the topic but mark it inline as:
   • NOT SURE: <precise ambiguity + what input/source is needed>

Avoid long verbatim quotes (keep any quote under ~25 words; prefer paraphrase).

References policy (keep it readable)

• Aim for ~3–6 references per chapter in a ## References section near the end.
• Prefer citing exact section/heading names from the MCP corpus.
• Avoid “current market practice today” claims unless supported by a dated authoritative source.

Iterative workflow (work in small batches)

Work in batches of 1–3 chapters at a time.

For each batch:

1. Read the whole chapter(s) (and relevant solutions) end-to-end.
2. Create a small checklist for the batch (in the relevant notes/phases/PHASE_XX_*.md and/or notes/PROGRESS.md).
3. Apply evidence-first corrections and clarity improvements.
4. Add/refresh references.
5. Run regression checks (links/anchors at minimum).
6. Update tracking:
   • notes/CHAPTER_TRACKER.md (Nav/Refs/Ev/Ex-Sol)
   • notes/PROGRESS.md (what completed; what’s next)
   • notes/DECISIONS.md (if a cross-chapter convention was decided)

Tooling / regression checks (required)

• After edits that touch links/anchors/navigation:
  • run python3 scripts/check_links.py
• If you add/rename headers or sections:
  • consider python3 scripts/insert_toc.py <chapter> (if TOC needs refresh)
  • consider python3 scripts/normalize_anchors.py <chapter> (only if anchors drift; minimize churn)

Note: Phase 01 upgrades link/anchor validation to catch real issues; treat validation as a gate before finishing a batch.

Guardrails (avoid accidental quality loss)

• Do not “simplify” by removing nuance; prefer adding structure and short summaries.
• Do not rename files or reorganize directories unless explicitly requested.
• Do not mass-reformat math or rewrite large portions unless needed for correctness.
• If you change an example or derivation, check and update the corresponding exercises/solutions.

GitHub Math Rendering Guardrails (Mandatory)

• ALWAYS keep refactor_plan/ git-ignored and untracked.

• NEVER force-add (git add -f) anything under refactor_plan/.

• Primary objective for math-hardening tasks: fix LaTeX/MathJax/GitHub rendering issues, not chapter prose.

• Do not rewrite, shorten, expand, or stylistically alter descriptive text when doing rendering fixes.

• Keep narrative meaning, ordering, pedagogy, and examples unchanged; only apply minimal syntax/layout edits required for correct rendering.

• GitHub renders Markdown and math in a pipeline: Markdown first, then math. This creates sharp hazards:

  • Inline code spans are never math-rendered: any TeX inside backticks (e.g., \Omega, \mathbb{Q}, \gt) will show literal backslashes on GitHub. Either (A) move it out of code and use $...$ / $$...$$, or (B) keep it in code but replace TeX macros with Unicode/plain text (e.g., Ω, ℙ, ℚ, ≤, →).
  • Math is not rendered inside Markdown link text ([...](...)), including TOC entries; avoid TeX there (use plain text / Unicode instead).
  • Math delimiters must survive Markdown unchanged: if Markdown inserts tags like <em>, <code>, or <a> inside what you intended as $...$, GitHub can’t detect/wrap the math (because the $...$ no longer lives in one text node). Inspect rendered HTML for <em> / <code> splitting math when debugging.
  • Render budget: adding too many math chunks can trip GitHub’s runtime limit and produce “Unable to render expression.” Prefer minimal/high-value conversions and avoid turning every TeX-ish code span into math.
  • Brace-light macros: to reduce GitHub’s math runtime budget, prefer single-token forms like \mathbb P, \mathbb Q, \mathbb E, \mathcal F, \mathcal G, \mathcal N, and \mathrm d over braced forms like \mathbb{P} / \mathcal{F} / \mathrm{d} when the argument is a single symbol.
  • Display-math paragraph separation: $$...$$ must be its own paragraph (blank lines before and after). Otherwise GitHub can wrap it as inline math.
  • Multi-line $$ blocks: if a $$...$$ block spans multiple lines (e.g., with aligned), put the delimiters on their own lines ($$ then content then $$). Avoid $$\\begin{aligned} / \\end{aligned}$$ and avoid blank lines inside the block; GitHub can leave the raw $$...$$ unwrapped.
  • Underscore emphasis hazard: underscores can trigger Markdown emphasis even inside $...$ (because Markdown runs first). Examples that can break:
    • $M^{\tau_n}_t = M_{t \wedge \tau_n}$ can become $M^{\tau_n}<em>t = M</em>{t \wedge \tau_n}$ in HTML.
    • Plain-text [S,S]_T ... $S_{t_1}$ can open emphasis at _T and close it at the next _ inside math. Fixes:
    • Escape plain-text underscores: [S,S]\_T, t\_i.
    • Add TeX-ignored spaces around subscript underscores in inline math: M^{\tau_n} _ t, M _ {t\wedge\tau_n}, S_ {t_1}.
    • Or move fragile inline expressions to display math blocks.
  • Inline-math delimiter adjacency: GitHub can fail to detect inline math when $...$ is “glued” to surrounding text (e.g., faster-than-$1/\sqrt{n}$). Prefer a space or parentheses: faster-than $1/\sqrt{n}$ or faster-than ($1/\sqrt{n}$).
  • Currency $ in prose/tables: currency-style tokens like $5, $100, $30M in plain text or tables can create an odd number of $ delimiters and break math detection. Prefer USD 5, USD 100, USD 30M, or escape as \$5 in prose (never inside math).
  • Asterisk emphasis hazard (*): repeated uses of ^* (e.g., many S^* in one paragraph) can be parsed as Markdown emphasis and split math. Prefer ^\ast / ^\star (e.g., S^\ast) instead of literal ^*.
  • Avoid typographic quotes around math: patterns like “$\lim$” can fail to wrap on GitHub. Prefer plain text (e.g., “swap $\lim$ and $\mathbb E$”) or ASCII quotes if needed.
  • Escaped punctuation inside math is eaten by Markdown: tokens like \%, \{, \}, \&, \,, \;, \! can lose their backslash before KaTeX runs. Use double-escaped forms in Markdown source like \\%, \\{, \\}, \\,, \\;, \\!, or avoid the punctuation (e.g., write PnL instead of P\&L).
  • Display math inside lists: GitHub can render list-indented $$...$$ blocks as inline math even when surrounded by blank lines. Prefer inline $...$ for short formulas, or move the $$...$$ block to a standalone (non-indented) paragraph.
  • Display math inside blockquotes: for blockquoted display math, prefer a multi-line form with > on each line:
    • > $$
    • > ...
    • > $$ Or switch to inline $...$ inside the quote.
  • Aligned blocks and list markers: if a $$...$$ block fails to wrap, lines that begin with +/-/* can be parsed as Markdown lists and corrupt the HTML. In aligned, avoid starting a continuation line with +; use &\\quad + \\dots or keep the + on the previous line.
  • For Markdown-collision cases (e.g., | inside tables), GitHub supports the inline delimiter form $`...`$ (dollar-backtick) as a fallback.

• Use inline math as $...$; display math as $$ ... $$ with blank lines around blocks.

• Avoid raw < and > in math; use \lt, \gt, \le, \ge.

• Do not use \operatorname{...}; use \mathrm{...} or plain symbols.

• Avoid risky macro+subscript forms like \text{X}_{i}; prefer X_i or plain identifiers.

• Avoid escaped dollar \$ inside math expressions; move currency outside math or write USD.

• Avoid math inside markdown emphasis *...$...$...*.

• Avoid fragile inline math in headings.

• Prefer stable symbols in prose when math is not needed.

• Be careful with math inside blockquotes/lists/tables; rewrite to safer plain text if fragile.

• Detect and fix malformed script forms like ^_, ^__, _^, ^^, dangling ^/_.

• Detect and fix trailing broken dollar delimiters like USD350$, USD35,000$.

Required after every file edit:

• python3 refactor_plan/github_math_escape_validate.py --paths <file> --max-errors 300
• .venv-github-render/bin/python refactor_plan/mathjax_render_check.py --paths <file> --max-errors 300

Required after push:

• python3 refactor_plan/github_api_render_validate.py --paths <file> --ref main --max-errors 300 --save-html-dir /tmp/<tag> --check-unwrapped --check-tex-in-code

A file is only done when GitHub API render validator returns OK.

MathJax TeX Input — Conformance & Generation Rules (MathJax v4 docs-aligned)

0) SCOPE & CORE REALITY

0.1 The MathJax TeX input processor is a JS implementation of a subset of TeX/LaTeX macros.

• Generators MUST assume “not full LaTeX”; unsupported macros/packages can fail or render wrong.
• Prefer widely supported core + AMS-style macros unless configuration is controlled.

0.2 Math delimiters are text markers configured in MathJax; HTML tags cannot be used as delimiters in normal config.

• Delimiters MUST be plain text strings (cannot include <); browser parsing happens before MathJax runs.
• If tag-style delimiters are required, that implies a custom render action (out of scope for normal config).

1) DELIMITER RULES (DETECTION + AUTHORING)

1.1 Default delimiters (if config unknown):

• Inline math MUST use: \(...\)
• Display math MUST use: \[...\] or $$...$$
• Inline $...$ MUST NOT be used unless it is known to be enabled in config.

1.2 Enabling single-dollar inline delimiters:

• To allow $...$ for inline math, config MUST explicitly add it to tex.inlineMath.

1.3 Display delimiters:

• Use \[...\] for LaTeX-like display delimiter style.
• Use $$...$$ only if TeX-style display delimiters are acceptable for the project.

1.4 Delimiter pairing:

• Every math segment MUST have properly paired start/end delimiters (no crossing or nesting).
• Generators SHOULD avoid nesting delimiters; use a single outer delimiter per math segment.

2) ESCAPES, LITERAL $, AND DELIMITER COLLISIONS

2.1 If $...$ inline delimiters are enabled, plan for currency/price text collisions.

2.2 Literal dollar sign handling:

• If processEscapes is true (common in v3+), \$ SHOULD be used for a literal $ in page text.
• Wrapping $ in HTML like <span>$</span> MAY be used to prevent delimiter matching.
• Reason: MathJax matches delimiters within the same HTML parent element.

2.3 Backslash literal handling (when processEscapes is true):

• \\ in text MAY represent a literal backslash (including sequences like \\$...$).

2.4 Version-aware HTML-in-TeX note:

• In MathJax v3 and below, TeX expressions MUST NOT contain HTML elements (except <br>, <wbr>, comments).
• In v4, HTML-in-TeX is only possible via the texhtml extension; do not assume it is enabled.

3) ENVIRONMENTS (\begin...\end...) AND “MATH MODE” BEHAVIOR

3.1 MathJax behavior differs from true LaTeX:

• Environments inside math delimiters will still be processed even if they would “start math mode” in LaTeX.

3.2 Environments outside delimiters:

• If tex.processEnvironments is true, MathJax also scans for \begin{X}...\end{X} outside delimiters.

3.3 Portability recommendation:

• To remain compatible with actual LaTeX, generators SHOULD wrap environments that require math mode (e.g., matrix-like environments) inside proper math delimiters rather than relying on processEnvironments.

3.4 Generation rule of thumb:

• Choose one:
• (A) Use delimiters with pure math content inside.
• (B) Use environment form outside delimiters (only with known/controlled config).
• Generators SHOULD avoid wrapping \begin{equation}...\end{equation} inside $$...$$ because it is non-idiomatic.

4) MACRO DEFINITIONS IN DOCUMENT CONTENT (TeX-level \def, \newcommand, etc.)

4.1 Supported macro-def commands include: \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment, \let.

4.2 Critical constraint:

• Unlike actual TeX, MathJax processes these macro definitions only when enclosed in math delimiters.
• Therefore, generators MUST place TeX macro definitions inside a math-delimited segment.

4.3 Scope:

• Macros defined this way are available for the rest of the page (document scope).

4.4 Ordering:

• Generators MUST emit macro definitions before first use (ideally in one early “definitions” block).

5) MACRO DEFINITIONS VIA CONFIGURATION (JS CONFIG: tex.macros / environments / active)

5.1 When controlling MathJax configuration:

• Define macros under MathJax = { tex: { macros: { ... } } }.

5.2 Macro key format:

• Keys MUST be the control sequence name without the leading backslash.
• Example: RR: "{\\bf R}" defines \RR.

5.3 Macro value formats:

• No-arg macro: value MUST be a replacement string.
• N-arg macro: value MUST be an array [replacementString, nArgs, (optional default values...)].

5.4 JavaScript string escaping:

• Replacement strings are JS string literals; backslash has special meaning.
• Generators MUST escape backslashes (e.g., "\\bf") or use String.raw for literals.

5.5 Environments and active characters:

• New environments MAY be defined under tex.environments.
• Active characters MAY be defined under tex.active.

6) EXTENSIONS / PACKAGES (WHAT MACROS EXIST DEPENDS ON LOADING)

6.1 Concept:

• Not all TeX macros are in the core input processor; many live in TeX extensions (packages).
• Some extensions autoload when their macros are used; some must be loaded explicitly.

6.2 Reading “supported commands” tables:

• Each macro/environment maps to a package name.
• If none listed: base package.
• Bold package name: preloaded by TeX-containing components (except input/tex-base).
• Italic package name: autoloaded by autoload; otherwise load explicitly.
• Text-mode note: most macros are not processed inside \text{...}; textmacros adds some coverage.

6.3 Explicit extension loading (when configuration is controlled):

• To enable an extension:
• (A) Load the component in loader.load (e.g., '[tex]/color'), and
• (B) Add it to tex.packages (e.g., packages: {'[+]': ['color']}).

6.4 Default extensions in common components:

• input/tex (and combined components with TeX) include ams, newcommand, noundefined, textmacros, require, autoload, configmacros.
• input/tex-base includes no extensions (base macros only).

6.5 Disabling extensions:

• Packages MAY be removed via tex.packages with {'[-]': [...]} (e.g., disable require/autoload).

6.6 Runtime loading:

• The non-standard macro \require{extension} MAY load an extension during typesetting.
• Generators SHOULD avoid relying on \require unless enabled and explicitly acceptable.

6.7 Extension option configuration:

• If an extension is loaded explicitly, options go under tex.<extensionName>.
• If expected via autoload/runtime load, config SHOULD be placed at top level using a key like '[tex]/color': { ... } to avoid pre-load “unknown option” errors.

7) PRACTICAL GENERATION PROFILES

7.1 Portable default profile (unknown config):

• Use \(...\) inline and \[...\] display.
• Avoid $...$ inline, avoid \require, and avoid custom macros unless defined in a math-delimited definitions block.

7.2 Dollar-inline enabled profile (controlled config):

• Enable $...$ via tex.inlineMath.
• Keep processEscapes true; ensure text uses \$ or <span>$</span> for literal currency.

7.3 Config-driven profile (controlled boot code):

• Define macros in tex.macros.
• Load needed extensions explicitly.
• Avoid runtime \require for deterministic behavior.

8) MINIMUM VALIDATION CHECKS AN AGENT SHOULD IMPLEMENT

8.1 Delimiter integrity:

• Verify delimiters are paired and non-overlapping.
• Forbid accidental single $ unless explicitly configured.

8.2 Macro hygiene:

• Flag use of undefined macros unless:
• (a) they are in base/AMS/newcommand/textmacros, or
• (b) the required extension is loaded.

8.3 Extension coverage:

• For every macro tagged with a package that is not preloaded/autoloaded, ensure explicit load plus tex.packages entries exist.

8.4 Portability warnings:

• Warn when relying on processEnvironments, \require, or texhtml behaviors without explicit config control.