Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(scheduled): ship five research playbooks

Haozhe Wue50f960a0f57
diff --git a/agent/src/scheduled_research/playbooks.py b/agent/src/scheduled_research/playbooks.py
new file mode 100644
index 000000000..096bb50bf
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks.py
@@ -0,0 +1,418 @@
+"""Ready-to-run research playbooks for the scheduled-research scheduler.
+
+A playbook is a markdown file with a YAML frontmatter header, living in the
+``playbooks/`` data directory beside this module. The frontmatter is the
+catalogue record (name, description, suggested cadence, the data capabilities
+a run needs); the body is the instruction text that becomes
+``ScheduledResearchJob.prompt`` verbatim.
+
+Two properties every template is written around, both forced by how the
+scheduler actually runs a job (``executor.py`` dispatches ``job.prompt`` through
+``src/api/scheduled_routes.py::_dispatch_scheduled_research_job``):
+
+* The prompt is persisted once at creation and re-sent unchanged on every fire,
+ so nothing may be baked in that is only true on the authoring day. Every
+ template resolves "today" at run time.
+* No template names a tool. A playbook states the data *capability* it needs in
+ plain language and lets the agent route to whatever tool provides it, so the
+ templates survive changes to the tool surface.
+
+Discovery order: the directory named by ``VIBE_TRADING_PLAYBOOK_DIR`` (when
+set) is searched before the bundled directory, and a user file wins on slug
+collision -- the override rule user skills already follow.
+
+Note on naming: this module and the data directory are both called
+``playbooks``. A directory without ``__init__.py`` is only a namespace-package
+candidate, which the import system consults *after* file loaders, so
+``import src.scheduled_research.playbooks`` always resolves to this module.
+``tests/test_research_playbooks.py`` pins that.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+import yaml
+
+from src.scheduled_research.models import (
+ JobStatus,
+ ScheduledResearchJob,
+ validate_schedule,
+ validate_timezone,
+ validate_timezone_shape,
+)
+
+_PLAYBOOK_DIR_ENV = "VIBE_TRADING_PLAYBOOK_DIR"
+_BUNDLED_DIR = Path(__file__).resolve().parent / "playbooks"
+
+# Opening ---, the YAML block, closing ---, then the body. Deliberately stricter
+# than src.agent.frontmatter: playbook metadata carries block sequences of
+# natural-language phrases (which contain commas), and that parser's inline
+# ``[a, b]`` form would shred them.
+_FRONTMATTER_RE = re.compile(r"^---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n(.*))?$", re.DOTALL)
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*([A-Za-z0-9_]+)\s*\}\}")
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+_REQUIRED_META = ("name", "description", "suggested_schedule", "data_capabilities")
+# One substituted variable is user text pasted into a prompt that is persisted
+# and replayed forever; cap it so a paste accident cannot bloat every run.
+_MAX_VARIABLE_CHARS = 4000
+
+# Sentinel for "caller did not pass a timezone", distinct from an explicit None
+# (which means UTC and is a legitimate override of a suggested zone).
+_KEEP = object()
+
+
+class PlaybookError(ValueError):
+ """Raised when a playbook file is malformed or used with bad arguments."""
+
+
+class PlaybookNotFoundError(PlaybookError):
+ """Raised when no playbook matches a requested slug."""
+
+
+@dataclass(frozen=True)
+class ResearchPlaybook:
+ """One parsed playbook template.
+
+ Attributes:
+ slug: Filename stem, the stable id used by the CLI and REST layers.
+ name: Human-readable title from the frontmatter.
+ description: One-line summary for catalogue listings.
+ suggested_schedule: Default schedule string, in the scheduler's format
+ (interval milliseconds or a 5-field cron expression).
+ suggested_timezone: Default IANA timezone key for cron evaluation, or
+ ``None`` for UTC.
+ markets: Market tags this playbook targets.
+ data_capabilities: Plain-language descriptions of the data a run needs.
+ Deliberately not tool names -- routing is the agent's job.
+ variables: Declared placeholder names mapped to their default text.
+ body: Instruction text, with ``{{placeholders}}`` unresolved.
+ path: File the playbook was loaded from.
+ """
+
+ slug: str
+ name: str
+ description: str
+ suggested_schedule: str
+ suggested_timezone: Optional[str]
+ markets: Tuple[str, ...]
+ data_capabilities: Tuple[str, ...]
+ variables: Dict[str, str] = field(default_factory=dict)
+ body: str = ""
+ path: Optional[Path] = None
+
+ def render(self, variables: Optional[Mapping[str, Any]] = None) -> str:
+ """Return the instruction body with placeholders substituted.
+
+ Args:
+ variables: Overrides keyed by declared variable name. A key that
+ is not declared by this playbook is an error rather than a
+ silent no-op. A blank value falls back to the declared default.
+
+ Returns:
+ The prompt text to hand to the scheduler.
+
+ Raises:
+ PlaybookError: If an undeclared variable is supplied or a value
+ exceeds the length cap.
+ """
+ values = dict(self.variables)
+ for key, raw in (variables or {}).items():
+ if key not in values:
+ raise PlaybookError(
+ f"playbook {self.slug!r} has no variable {key!r}; declared: {sorted(values)}"
+ )
+ text = str(raw).strip()
+ if len(text) > _MAX_VARIABLE_CHARS:
+ raise PlaybookError(
+ f"playbook variable {key!r} is {len(text)} chars; the cap is {_MAX_VARIABLE_CHARS}"
+ )
+ if text:
+ values[key] = text
+ # Every placeholder in the body was checked against ``variables`` at
+ # load time, so this substitution cannot leave one behind.
+ return _PLACEHOLDER_RE.sub(lambda m: values[m.group(1)], self.body)
+
+ def to_job(
+ self,
+ *,
+ job_id: Optional[str] = None,
+ schedule: Optional[str] = None,
+ timezone: Any = _KEEP,
+ variables: Optional[Mapping[str, Any]] = None,
+ config: Optional[Mapping[str, Any]] = None,
+ next_run_at: Optional[int] = None,
+ now_ms: Optional[int] = None,
+ ) -> ScheduledResearchJob:
+ """Build a schedulable job from this playbook.
+
+ The result is ready for ``ScheduledResearchJobStore.upsert`` and mirrors
+ what ``POST /scheduled-runs`` builds, including its first-fire rule: a
+ cron job carrying a timezone first fires at its first authored
+ occurrence, while interval jobs and timezone-less jobs fire immediately.
+
+ Args:
+ job_id: Explicit job id. Defaults to a slug-prefixed unique id.
+ schedule: Schedule override. Defaults to ``suggested_schedule``.
+ timezone: Timezone override. Omit to keep ``suggested_timezone``;
+ pass ``None`` explicitly to force UTC.
+ variables: Placeholder overrides, as for :meth:`render`.
+ config: Session config forwarded to the agent run. A ``playbook``
+ provenance key is added when the caller did not set one;
+ ``AgentConfigOverride`` ignores unknown keys
+ (``src/config/schema.py`` ``extra="ignore"``), so this is inert
+ for config resolution.
+ next_run_at: Explicit first-fire epoch-ms, bypassing the rule above.
+ now_ms: Injectable clock for tests, in epoch milliseconds.
+
+ Returns:
+ A ``PENDING`` :class:`ScheduledResearchJob`.
+
+ Raises:
+ PlaybookError: If a supplied variable is invalid.
+ ValueError: If the schedule or timezone is malformed, or the cron
+ expression has no occurrence within the executor's search
+ window.
+ """
+ resolved_schedule = (schedule if schedule is not None else self.suggested_schedule).strip()
+ validate_schedule(resolved_schedule)
+ tz = self.suggested_timezone if timezone is _KEEP else timezone
+ validate_timezone(tz)
+
+ now = int(time.time() * 1000) if now_ms is None else now_ms
+ if next_run_at is None:
+ next_run_at = now
+ if tz is not None and not resolved_schedule.isdigit():
+ # Imported here, not at module scope: the executor pulls in the
+ # env config and the tool-redaction module (~0.5s), which a CLI
+ # that only lists the catalogue should not pay for.
+ from src.scheduled_research.executor import next_due
+
+ next_run_at = next_due(resolved_schedule, now, tz)
+
+ job_config: Dict[str, Any] = dict(config or {})
+ job_config.setdefault("playbook", self.slug)
+
+ return ScheduledResearchJob(
+ id=job_id or f"playbook-{self.slug}-{uuid.uuid4().hex[:8]}",
+ prompt=self.render(variables),
+ schedule=resolved_schedule,
+ next_run_at=next_run_at,
+ status=JobStatus.PENDING,
+ created_at=now,
+ config=job_config,
+ timezone=tz,
+ )
+
+ def to_dict(self, include_body: bool = False) -> Dict[str, Any]:
+ """Return a JSON-serializable catalogue record.
+
+ Args:
+ include_body: Include the raw instruction body. Off by default so
+ a catalogue listing stays small.
+
+ Returns:
+ A plain dict suitable for a REST response or CLI rendering.
+ """
+ data: Dict[str, Any] = {
+ "slug": self.slug,
+ "name": self.name,
+ "description": self.description,
+ "suggested_schedule": self.suggested_schedule,
+ "suggested_timezone": self.suggested_timezone,
+ "markets": list(self.markets),
+ "data_capabilities": list(self.data_capabilities),
+ "variables": dict(self.variables),
+ }
+ if include_body:
+ data["body"] = self.body
+ return data
+
+
+def _string_list(value: Any, key: str, path: Path) -> Tuple[str, ...]:
+ """Coerce a frontmatter value to a tuple of non-empty strings."""
+ if isinstance(value, str):
+ value = [value]
+ if not isinstance(value, list) or not value:
+ raise PlaybookError(f"playbook {path}: {key!r} must be a non-empty list of strings")
+ items = tuple(str(item).strip() for item in value)
+ if any(not item for item in items):
+ raise PlaybookError(f"playbook {path}: {key!r} contains an empty entry")
+ return items
+
+
+def load_playbook_file(path: Path) -> ResearchPlaybook:
+ """Parse one playbook markdown file.
+
+ Args:
+ path: Path to a ``.md`` playbook file.
+
+ Returns:
+ The parsed :class:`ResearchPlaybook`.
+
+ Raises:
+ PlaybookError: If the filename is not a valid slug, the file has no
+ frontmatter, is missing a required key, declares a malformed
+ schedule/timezone, has an empty body, or uses a placeholder it
+ never declared.
+ OSError: If the file cannot be read.
+ """
+ # Checked here, not only in get_playbook: the filename IS the slug, so a
+ # file that list_playbooks would happily enumerate but get_playbook would
+ # refuse (``My_Playbook.md``) must fail loudly at load rather than appear
+ # in the catalogue as an entry nobody can select.
+ if not _SLUG_RE.fullmatch(path.stem):
+ raise PlaybookError(
+ f"playbook {path}: filename stem {path.stem!r} is not a valid slug; "
+ "use lowercase letters, digits and hyphens (e.g. 'my-playbook.md')"
+ )
+ # utf-8-sig, not utf-8: a BOM left by a Windows editor would otherwise sit
+ # in front of the opening '---' and surface as a bogus "missing frontmatter".
+ text = path.read_text(encoding="utf-8-sig")
+ match = _FRONTMATTER_RE.match(text)
+ if match is None:
+ raise PlaybookError(f"playbook {path}: missing '---' YAML frontmatter header")
+
+ try:
+ meta = yaml.safe_load(match.group(1) or "") or {}
+ except yaml.YAMLError as exc:
+ raise PlaybookError(f"playbook {path}: frontmatter is not valid YAML ({exc})") from exc
+ if not isinstance(meta, dict):
+ raise PlaybookError(f"playbook {path}: frontmatter must be a mapping")
+
+ missing = [key for key in _REQUIRED_META if not meta.get(key)]
+ if missing:
+ raise PlaybookError(f"playbook {path}: frontmatter is missing {missing}")
+
+ body = (match.group(2) or "").strip()
+ if not body:
+ raise PlaybookError(f"playbook {path}: body is empty")
+
+ schedule = str(meta["suggested_schedule"]).strip()
+ try:
+ validate_schedule(schedule)
+ except ValueError as exc:
+ raise PlaybookError(f"playbook {path}: {exc}") from exc
+
+ tz = meta.get("suggested_timezone")
+ tz = str(tz).strip() or None if tz is not None else None
+ # Shape only, not resolution: a bundled zone key that this host's tz
+ # database lacks must not make the whole catalogue unlistable. to_job()
+ # resolves it, the same place POST /scheduled-runs does.
+ validate_timezone_shape(tz)
+
+ raw_variables = meta.get("variables") or {}
+ if not isinstance(raw_variables, dict):
+ raise PlaybookError(f"playbook {path}: 'variables' must be a mapping of name to default")
+ variables = {str(k): str(v) for k, v in raw_variables.items()}
+
+ undeclared = sorted(set(_PLACEHOLDER_RE.findall(body)) - set(variables))
+ if undeclared:
+ raise PlaybookError(f"playbook {path}: body uses undeclared variables {undeclared}")
+
+ return ResearchPlaybook(
+ slug=path.stem,
+ name=str(meta["name"]).strip(),
+ description=str(meta["description"]).strip(),
+ suggested_schedule=schedule,
+ suggested_timezone=tz,
+ markets=_string_list(meta.get("markets") or ["global"], "markets", path),
+ data_capabilities=_string_list(meta["data_capabilities"], "data_capabilities", path),
+ variables=variables,
+ body=body,
+ path=path,
+ )
+
+
+def playbook_dirs(directory: Optional[Path] = None) -> List[Path]:
+ """Return the directories searched for playbooks, highest priority first.
+
+ Args:
+ directory: When given, the only directory searched.
+
+ Returns:
+ A list of directory paths (which may not exist).
+ """
+ if directory is not None:
+ return [Path(directory).expanduser()]
+ dirs: List[Path] = []
+ override = os.getenv(_PLAYBOOK_DIR_ENV, "").strip()
+ if override:
+ dirs.append(Path(override).expanduser())
+ dirs.append(_BUNDLED_DIR)
+ return dirs
+
+
+def list_playbooks(directory: Optional[Path] = None) -> List[ResearchPlaybook]:
+ """Load every available playbook, sorted by slug.
+
+ A slug found in an earlier directory shadows the same slug later, so a user
+ file overrides the bundled one.
+
+ Args:
+ directory: Search only this directory instead of the default chain.
+
+ Returns:
+ The parsed playbooks, sorted by slug.
+
+ Raises:
+ PlaybookError: If any discovered file fails to parse. A broken playbook
+ is surfaced, not skipped -- silently dropping it would hide the
+ file the user is trying to fix.
+ """
+ found: Dict[str, ResearchPlaybook] = {}
+ for candidate_dir in playbook_dirs(directory):
+ if not candidate_dir.is_dir():
+ continue
+ for path in sorted(candidate_dir.glob("*.md")):
+ if path.stem not in found:
+ found[path.stem] = load_playbook_file(path)
+ return [found[slug] for slug in sorted(found)]
+
+
+def get_playbook(slug: str, directory: Optional[Path] = None) -> ResearchPlaybook:
+ """Load a single playbook by slug.
+
+ Args:
+ slug: Playbook slug (its filename stem).
+ directory: Search only this directory instead of the default chain.
+
+ Returns:
+ The parsed playbook.
+
+ Raises:
+ PlaybookNotFoundError: If the slug is malformed or no file matches.
+ PlaybookError: If the matching file fails to parse.
+ """
+ if not isinstance(slug, str) or not _SLUG_RE.fullmatch(slug):
+ raise PlaybookNotFoundError(f"invalid playbook slug: {slug!r}")
+ for candidate_dir in playbook_dirs(directory):
+ path = candidate_dir / f"{slug}.md"
+ if path.is_file():
+ return load_playbook_file(path)
+ available = ", ".join(p.slug for p in list_playbooks(directory)) or "none"
+ raise PlaybookNotFoundError(f"unknown playbook {slug!r}; available: {available}")
+
+
+def build_job(slug: str, directory: Optional[Path] = None, **kwargs: Any) -> ScheduledResearchJob:
+ """Load a playbook by slug and turn it into a schedulable job.
+
+ Args:
+ slug: Playbook slug.
+ directory: Search only this directory instead of the default chain.
+ **kwargs: Forwarded to :meth:`ResearchPlaybook.to_job`.
+
+ Returns:
+ A ``PENDING`` :class:`ScheduledResearchJob`.
+
+ Raises:
+ PlaybookNotFoundError: If no playbook matches *slug*.
+ PlaybookError: If the file fails to parse or a variable is invalid.
+ """
+ return get_playbook(slug, directory).to_job(**kwargs)
diff --git a/agent/src/scheduled_research/playbooks/a-share-money-flow.md b/agent/src/scheduled_research/playbooks/a-share-money-flow.md
new file mode 100644
index 000000000..c5b764f62
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks/a-share-money-flow.md
@@ -0,0 +1,111 @@
+---
+name: A-Share Money Flow Review
+description: Post-close A-share flow review — exchange public trading disclosures, northbound flows, sector money flow and the limit-up board.
+markets: [cn]
+suggested_schedule: "0 19 * * 1-5"
+suggested_timezone: Asia/Shanghai
+data_capabilities:
+ - Exchange daily public trading disclosures naming the top buying and selling seats for each listed stock
+ - Northbound Stock Connect flow figures for the session
+ - Per-stock and per-sector money flow broken down by order size
+ - Margin financing and securities lending balances by stock and in aggregate
+ - Sector and industry performance rankings for the session
+ - Daily price, volume and turnover history for individual A-share tickers
+variables:
+ watchlist: (no watch list configured)
+---
+
+# A-share money flow review
+
+Review where money actually went in the A-share session that just closed.
+
+Resolve the current date from the run environment and confirm the session date
+from the retrieved data itself. On a holiday or a half-day the newest available
+session may not be today — say which date the report covers, and say it in the
+first line.
+
+## Inputs
+
+- Watch list: {{watchlist}}
+
+The watch list only adds a final cross-reference section. The rest of the
+report is market-wide and runs with or without it.
+
+## Data to gather
+
+1. The exchange's daily public trading disclosures for the session: which
+ stocks qualified, why they qualified, and the top buying and selling seats
+ on each, with amounts.
+2. Northbound Stock Connect flow for the session, at whatever granularity the
+ source actually publishes.
+3. Money flow by order size, both at the sector level and for the day's most
+ active names.
+4. Margin financing and securities lending balances for the session, in
+ aggregate and for any name that moved sharply.
+5. Sector and industry performance for the session, ranked.
+6. The stocks that closed at their daily price limit, up or down, and the
+ turnover and time-to-limit information the source provides.
+7. For each watch-list symbol, its session return, turnover, and whether it
+ appeared in any of the above.
+
+## Method
+
+- A-share boards apply different daily price limits, and stocks under special
+ treatment apply a different one again. Determine the applicable limit for a
+ stock from the retrieved data rather than assuming one number for the whole
+ market, and state which board each limit-up name trades on.
+- Seat-level disclosures identify a counterparty channel, not an investor.
+ Describe what the disclosure literally shows — this seat bought this amount —
+ and do not name or characterise who sat behind it.
+- If the northbound source publishes only end-of-day aggregates, use the
+ aggregates and say so. Do not reconstruct an intraday path from an end-of-day
+ number.
+- Cross-check the day's story: a sector leading on performance but not on money
+ flow, or a limit-up name with no matching flow, is worth one line as a
+ contradiction rather than being smoothed over.
+- Report flow in the currency and unit the source used, and label the unit.
+
+## When data is missing
+
+A source that returns nothing, errors out, or is not configured is a fact to
+report, not a gap to fill.
+
+- Name every missing item explicitly in a `Data gaps` section, with the reason
+ when the failure gave one.
+- Continue using only the evidence actually retrieved.
+- Never substitute a value from memory, from a general prior, from a
+ third-party summary, or from an earlier run of this playbook. A flow number
+ that did not come back on this run does not appear in this report.
+- Never present a stale figure as current. Several of these disclosures are
+ published at different times after the close; if the newest available record
+ is from a previous session, print its date beside it and label it as the
+ previous session, not as today.
+- If a whole section has no evidence, keep its heading and write
+ `no data retrieved` under it.
+- Every figure carries its session date, its unit, and the source it came from.
+
+## Output
+
+Markdown, in this order:
+
+1. `## Session` — the date this report covers and the index closes for it.
+2. `## Northbound` — the flow figures retrieved, with their granularity stated.
+3. `## Sector flow` — ranked table: sector, session return, net flow, unit.
+4. `## Public trading disclosures` — per stock: reason it qualified, top buy
+ seats, top sell seats, net.
+5. `## Limit board` — limit-up and limit-down names, board, turnover, and the
+ sector they cluster in if they cluster at all.
+6. `## Margin balances` — aggregate change and any notable per-stock change.
+7. `## Watch list cross-reference` — omit when no watch list was supplied.
+8. `## Data gaps` — always present; write `none` when nothing was missing.
+
+## Boundaries
+
+- Factual review of one session. No buy, sell, or hold calls, no price
+ targets, no next-day predictions.
+- Do not place, modify, or cancel any order, and do not touch a live trading
+ connector.
+- Do not attribute flows to a named institution, fund, or individual. Report
+ the disclosed channel and amount.
+- Concentrated buying is an observation, not a signal. Say what was disclosed
+ and stop there.
diff --git a/agent/src/scheduled_research/playbooks/earnings-season-tracker.md b/agent/src/scheduled_research/playbooks/earnings-season-tracker.md
new file mode 100644
index 000000000..1b5dcc2ff
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks/earnings-season-tracker.md
@@ -0,0 +1,108 @@
+---
+name: Earnings Season Tracker
+description: Upcoming earnings dates for held and watched names, plus what changed in expectations and in the last reported quarter.
+markets: [us, cn, hk, global]
+suggested_schedule: "0 7 * * 1-5"
+suggested_timezone: America/New_York
+data_capabilities:
+ - Scheduled and confirmed earnings dates for a given list of symbols
+ - Reported income-statement and cash-flow lines for recent fiscal periods, with the filing or announcement date
+ - Regulatory filings and company announcements covering results, guidance and pre-announcements
+ - Analyst estimate and rating changes with the date each change was published
+ - Recent daily price and volume history around the reporting dates
+variables:
+ universe: (no holdings or watch list configured)
+ horizon_days: "14"
+---
+
+# Earnings season tracker
+
+Track the reporting calendar and the expectation drift for **{{universe}}**
+over the next {{horizon_days}} days.
+
+Resolve the current date from the run environment. This text is stored once and
+replayed on every fire, so the reporting window must be computed at run time,
+never read off this page.
+
+## Inputs
+
+- Universe: {{universe}}
+- Horizon: {{horizon_days}} calendar days forward from the run date
+
+If the universe above is empty or says none is configured, stop after saying so
+in one line. Do not substitute an index, a sector, or a set of well-known
+tickers.
+
+## Data to gather
+
+For each symbol in the universe:
+
+1. The next earnings date, and whether it is confirmed by the company or is an
+ estimate. Keep that distinction — it is the single most misread field on
+ any earnings calendar.
+2. The fiscal period that will be reported, and the date the previous period
+ was reported.
+3. The revenue, operating income, net income and operating cash flow of the
+ last two reported periods, each tagged with the date the figures were filed
+ or announced.
+4. Any consensus estimate for the coming period, with the date the estimate was
+ last revised, plus rating or target changes published since the previous
+ report.
+5. Company announcements since the previous report that touch guidance:
+ pre-announcements, revisions, profit warnings, restatements.
+6. The symbol's price change and volume over the twenty sessions before the run
+ date.
+
+## Method
+
+- Sort by earnings date ascending. Names reporting inside the horizon come
+ first; the rest go into a short tail section.
+- Report expectation drift as a delta between two dated observations, never as
+ a level. "Consensus EPS revised from X on date A to Y on date B" is usable;
+ "consensus is Y" is not.
+- Where the last reported period contains a one-off (disposal, impairment,
+ tax item) that a filing calls out, say so beside the growth figure.
+- Do not compute a surprise number unless both the reported figure and the
+ pre-report estimate were actually retrieved on this run.
+
+## When data is missing
+
+A source that returns nothing, errors out, or is not configured is a fact to
+report, not a gap to fill.
+
+- Name every missing item explicitly in a `Data gaps` section, with the reason
+ when the failure gave one.
+- Continue using only the evidence actually retrieved.
+- Never substitute a value from memory, from a general prior, from a
+ third-party summary, or from an earlier run of this playbook. A number that
+ did not come back from a source on this run does not appear in this report.
+- Never present a stale figure as current. If the freshest value available is
+ older than the window this report covers, print its as-of date beside it.
+- If a whole section has no evidence, keep its heading and write
+ `no data retrieved` under it.
+- Every figure carries its as-of date and the source it came from.
+- An earnings date that could not be retrieved is listed as unknown. Do not
+ infer it from the previous year's reporting pattern.
+
+## Output
+
+Markdown, in this order:
+
+1. `## Reporting inside the horizon` — a table: symbol, date, confirmed or
+ estimated, fiscal period, 20-day price change.
+2. `## Expectation changes` — one bullet per dated revision, most recent first.
+ Omit the section body and write `none retrieved` if nothing was found.
+3. `## Last reported quarter` — per symbol, the two-period comparison of the
+ lines gathered above, with filing dates.
+4. `## Announcements since last report` — dated, one line each.
+5. `## Reporting after the horizon` — symbol and date only.
+6. `## Data gaps` — always present; write `none` when nothing was missing.
+
+## Boundaries
+
+- Factual tracking only. No buy, sell, or hold calls, no price targets, no
+ view on whether a name will beat or miss.
+- Do not place, modify, or cancel any order, and do not touch a live trading
+ connector.
+- Do not model a future quarter. This playbook reports what has been filed and
+ what estimates have been published, and nothing else.
diff --git a/agent/src/scheduled_research/playbooks/institutional-holdings-diff.md b/agent/src/scheduled_research/playbooks/institutional-holdings-diff.md
new file mode 100644
index 000000000..d29e7979e
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks/institutional-holdings-diff.md
@@ -0,0 +1,113 @@
+---
+name: Institutional Holdings Diff
+description: Quarter-over-quarter position changes disclosed by institutional managers, diffed for a chosen set of managers or symbols.
+markets: [us]
+suggested_schedule: "0 9 15 2,5,8,11 *"
+suggested_timezone: America/New_York
+data_capabilities:
+ - Quarterly institutional holdings disclosures filed with the U.S. securities regulator, per manager and per reporting period
+ - Filing index lookup that returns the filing date and the period the filing covers
+ - Company profile and share-count reference data for the disclosed symbols
+ - Daily price history covering the disclosed period and the interval since it ended
+variables:
+ managers: (no managers specified)
+ symbols: (no symbols specified)
+---
+
+# Institutional holdings diff
+
+Diff the two most recently disclosed quarters of institutional holdings for
+the managers and symbols below.
+
+Resolve the current date from the run environment, then determine which
+reporting periods are actually available from the filings you retrieve. Do not
+assume a period is available because the calendar says it should be.
+
+## Inputs
+
+- Managers: {{managers}}
+- Symbols: {{symbols}}
+
+At least one of the two must be supplied. If both are empty, stop and say so in
+one line — do not substitute a list of famous investors or a market-wide scan.
+When managers are given, diff each manager's whole book. When only symbols are
+given, diff the disclosed holders of those symbols.
+
+## Data to gather
+
+1. For each manager, the two most recent quarterly holdings disclosures: the
+ period each one covers, the date each one was filed, and whether it is an
+ original filing or an amendment.
+2. The full position list from each of those two filings — symbol, share count,
+ disclosed value.
+3. For symbols that appear in the diff, the current share count and basic
+ company reference data.
+4. Price history spanning the disclosed period and the interval between the
+ period end and the run date.
+
+## Method
+
+- These filings are due within 45 days of the quarter end. Every position
+ therefore describes the manager's book **as of the period-end date**, not as
+ of today. Print the period-end date in the report header and repeat it in any
+ section that states a position size.
+- Classify each change as new, exited, increased, reduced, or unchanged, using
+ share counts rather than disclosed values — value moves with price and will
+ otherwise be mistaken for activity.
+- Report value changes separately, and split them into the part explained by
+ the price move over the period and the residual.
+- Check for share splits between the two periods before comparing share counts.
+ If a split occurred and the filings are not adjusted for it, say so and do
+ not report a mechanical change as a position change.
+- An amended filing supersedes the original for the same period. Use the latest
+ amendment and say that you did.
+- These disclosures cover only the security types the rule requires — broadly,
+ U.S.-listed equity and certain related instruments. Short positions, cash,
+ non-U.S. listings and most derivatives are not disclosed here. State this
+ limitation once in the report rather than presenting the filing as the
+ manager's full book.
+
+## When data is missing
+
+A source that returns nothing, errors out, or is not configured is a fact to
+report, not a gap to fill.
+
+- Name every missing item explicitly in a `Data gaps` section, with the reason
+ when the failure gave one.
+- Continue using only the evidence actually retrieved.
+- Never substitute a value from memory, from a general prior, from a
+ third-party summary, or from an earlier run of this playbook. A holding that
+ did not come back from a filing on this run does not appear in this report.
+- Never present a stale figure as current. Every position line carries the
+ period-end date of the filing it came from.
+- If only one period could be retrieved for a manager, report that single
+ period as a snapshot and explicitly state that no diff was possible. Do not
+ diff against remembered or assumed prior holdings.
+- If a whole section has no evidence, keep its heading and write
+ `no data retrieved` under it.
+
+## Output
+
+Markdown, in this order:
+
+1. `## Coverage` — the managers and symbols actually resolved, the two periods
+ compared, and each filing's filing date and amendment status.
+2. `## New positions` — table: manager, symbol, shares, disclosed value.
+3. `## Exited positions` — same columns, from the earlier period.
+4. `## Increased` and `## Reduced` — table: manager, symbol, share change,
+ percent change in shares, value change, price change over the period.
+5. `## Concentration` — each manager's top holdings by disclosed value in the
+ later period, and how that share shifted between periods.
+6. `## Limitations` — the as-of lag and the instrument-coverage limitation,
+ stated in two lines.
+7. `## Data gaps` — always present; write `none` when nothing was missing.
+
+## Boundaries
+
+- Factual diff of public filings. No buy, sell, or hold calls, no price
+ targets, no reading of intent into a manager's trade.
+- Do not place, modify, or cancel any order, and do not touch a live trading
+ connector.
+- Do not describe a disclosed position as a current position. The lag between
+ the period end and the run date is the single most important caveat in this
+ report; keep it visible.
diff --git a/agent/src/scheduled_research/playbooks/portfolio-checkup.md b/agent/src/scheduled_research/playbooks/portfolio-checkup.md
new file mode 100644
index 000000000..859798ce8
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks/portfolio-checkup.md
@@ -0,0 +1,110 @@
+---
+name: Portfolio Checkup
+description: Periodic risk x-ray of a stated book — exposure, concentration, correlation and drawdown, measured from retrieved prices.
+markets: [global, cn, hk, us, crypto]
+suggested_schedule: "0 9 * * 6"
+suggested_timezone: Asia/Shanghai
+data_capabilities:
+ - Daily price history long enough to compute volatility, correlation and drawdown for every position
+ - Portfolio-level risk decomposition — position weights, volatility contribution, correlation structure, drawdown
+ - Sector, industry and listing-venue classification for each holding
+ - Benchmark index history for the same window as the holdings
+ - Currency reference rates when the book spans more than one currency
+variables:
+ holdings: (no holdings provided — the report cannot run without them)
+ benchmark: the broad index of the book's home market
+ lookback_days: "252"
+---
+
+# Portfolio checkup
+
+Run a risk x-ray on the book below over a {{lookback_days}}-session lookback,
+against **{{benchmark}}**.
+
+Resolve the current date from the run environment; the lookback window ends on
+the most recent session for which prices were actually retrieved, not on an
+assumed date.
+
+## Inputs
+
+- Holdings: {{holdings}}
+- Benchmark: {{benchmark}}
+- Lookback: {{lookback_days}} sessions
+
+If no holdings are supplied, stop and say so in one line. Do not invent a book,
+do not reuse a book from an earlier run, and do not fall back to an index as a
+stand-in portfolio.
+
+## Data to gather
+
+1. Daily closes for every holding covering the full lookback, plus the same
+ window for the benchmark.
+2. Position weights implied by the supplied quantities and the latest retrieved
+ close. If the input gives weights rather than quantities, use them as given
+ and say so.
+3. A risk decomposition of the book: per-position volatility contribution,
+ pairwise correlation structure, realised portfolio volatility, maximum
+ drawdown and the dates it ran between.
+4. Sector, industry and listing venue for each holding.
+5. Where holdings settle in different currencies, the reference rates needed to
+ express everything in one currency, with the rate date.
+
+## Method
+
+- Compute every statistic from the price series retrieved on this run. Report
+ the exact number of sessions each statistic used.
+- A holding whose price history is shorter than the lookback is measured over
+ its own available window, and that shorter window is printed beside its
+ numbers. Never pad, interpolate, or back-fill a missing series.
+- Concentration is reported on three axes at once: single position, sector, and
+ listing venue or currency. A book can look diversified on one and be
+ concentrated on another.
+- Drawdown is stated with both its depth and its date range, and whether the
+ book has recovered.
+- If the book contains both long and short exposure, say so and state which
+ statistics remain meaningful under netting rather than reporting a single
+ blended number as if the book were long-only.
+
+## When data is missing
+
+A source that returns nothing, errors out, or is not configured is a fact to
+report, not a gap to fill.
+
+- Name every missing item explicitly in a `Data gaps` section, with the reason
+ when the failure gave one.
+- Continue using only the evidence actually retrieved.
+- Never substitute a value from memory, from a general prior, from a
+ third-party summary, or from an earlier run of this playbook. A price series
+ that did not come back on this run does not enter any calculation.
+- Never present a stale figure as current. Print the as-of date of the last
+ close used for every holding.
+- If a whole section has no evidence, keep its heading and write
+ `no data retrieved` under it.
+- A holding whose prices could not be retrieved is excluded from the
+ statistics, listed by name in `Data gaps`, and its weight is reported as
+ unmeasured — never silently dropped and never redistributed across the rest.
+
+## Output
+
+Markdown, in this order:
+
+1. `## Book summary` — number of positions, currencies, as-of date, sessions
+ used.
+2. `## Exposure` — table of holding, weight, sector, venue, last close, as-of
+ date.
+3. `## Concentration` — top position weight, top three combined, largest sector
+ weight, largest venue or currency weight.
+4. `## Risk` — realised volatility, volatility contribution ranking, the most
+ correlated pairs, and the same volatility figure for the benchmark.
+5. `## Drawdown` — maximum drawdown, its date range, current distance from
+ peak; the same for the benchmark.
+6. `## Data gaps` — always present; write `none` when nothing was missing.
+
+## Boundaries
+
+- Measurement only. No buy, sell, or hold calls, no price targets, no
+ rebalancing instructions, no target weights, no view on any holding.
+- Do not place, modify, or cancel any order, and do not touch a live trading
+ connector.
+- Historical statistics describe the window measured. Do not present them as a
+ forecast of future risk.
diff --git a/agent/src/scheduled_research/playbooks/premarket-brief.md b/agent/src/scheduled_research/playbooks/premarket-brief.md
new file mode 100644
index 000000000..64e7ebb94
--- /dev/null
+++ b/agent/src/scheduled_research/playbooks/premarket-brief.md
@@ -0,0 +1,99 @@
+---
+name: Pre-market Brief
+description: Overnight global market moves plus today's watch items, assembled before the home session opens.
+markets: [global, cn, hk, us]
+suggested_schedule: "30 8 * * 1-5"
+suggested_timezone: Asia/Shanghai
+data_capabilities:
+ - Daily index levels and percentage changes for the major overnight equity sessions
+ - Overnight moves in benchmark commodities, major FX pairs and government bond yields
+ - Headline news published since the previous home-market close, with publication timestamps
+ - Recent daily price and volume history for the symbols on the user's watch list
+ - Macro releases and corporate events scheduled for the current date
+variables:
+ home_market: China A-shares
+ watchlist: (no watch list configured)
+---
+
+# Pre-market brief
+
+Produce a pre-open briefing for **{{home_market}}**.
+
+Resolve the current date and time from the run environment on every run. This
+instruction text is stored once and replayed on every fire, so it contains no
+date of its own — never assume the day it was written is the day it is running.
+
+## Inputs
+
+- Home market: {{home_market}}
+- Watch list: {{watchlist}}
+
+If the watch list above is empty or says none is configured, skip the
+per-symbol section entirely and say so in one line rather than inventing a
+list of symbols.
+
+## Data to gather
+
+1. Closing level and percentage change of the major equity indices whose
+ sessions ran while the home market was shut, plus the home market's own
+ previous close.
+2. Overnight change in the benchmark energy and metals contracts, the main FX
+ pairs relevant to the home market, and the 10-year government bond yield of
+ the home market and of the United States.
+3. Headlines published since the previous home-market close that name the home
+ market, its index, its regulator, or any watch-list symbol. Keep the
+ publication timestamp attached to each headline.
+4. For each watch-list symbol: the last close, the change over the last five
+ sessions, and volume against its recent average.
+5. Anything scheduled for today — macro data releases, central bank events,
+ earnings dates, index changes — that falls in the home market's session.
+
+## Method
+
+- Order the report by how much it can move the home session, not by how
+ interesting the headline is.
+- Separate what moved from why it moved. Only assert a cause when a retrieved
+ source states that cause; otherwise report the move and the coincident
+ headline as two separate facts.
+- A move smaller than the instrument's own recent daily range is noise. Say so
+ instead of narrating it.
+
+## When data is missing
+
+A source that returns nothing, errors out, or is not configured is a fact to
+report, not a gap to fill.
+
+- Name every missing item explicitly in a `Data gaps` section, with the reason
+ when the failure gave one.
+- Continue using only the evidence actually retrieved.
+- Never substitute a value from memory, from a general prior, from a
+ third-party summary, or from an earlier run of this playbook. A number that
+ did not come back from a source on this run does not appear in this report.
+- Never present a stale figure as current. If the freshest value available is
+ older than the window this brief covers, print its as-of date beside it.
+- If a whole section has no evidence, keep its heading and write
+ `no data retrieved` under it.
+- Every figure carries its as-of date and the source it came from.
+
+## Output
+
+Markdown, in this order:
+
+1. `## Overnight tape` — a table of index / commodity / FX / yield, level,
+ change, as-of timestamp.
+2. `## What changed overnight` — at most five bullets, each tied to a dated
+ headline.
+3. `## Watch list` — one line per symbol: last close, 5-day change, volume vs
+ average, and any dated news naming it.
+4. `## On today's calendar` — scheduled releases and events, with local times.
+5. `## Data gaps` — always present; write `none` when nothing was missing.
+
+Keep the whole brief under roughly 700 words.
+
+## Boundaries
+
+- This is a factual briefing. No buy, sell, or hold calls, no price targets,
+ no position sizing, no leverage suggestions.
+- Do not place, modify, or cancel any order, and do not touch a live trading
+ connector.
+- Do not forecast the day's direction. Report the setup; the reader decides.
diff --git a/agent/tests/test_research_playbooks.py b/agent/tests/test_research_playbooks.py
new file mode 100644
index 000000000..166160dfb
--- /dev/null
+++ b/agent/tests/test_research_playbooks.py
@@ -0,0 +1,425 @@
+"""Tests for the scheduled-research playbook catalogue.
+
+Covers: bundled-template invariants (schedule/timezone validity, the
+missing-data rule, no tool names in any body), the markdown+frontmatter loader
+and its failure modes, variable rendering, the user-directory override, and
+job construction against the real job store and the real cron evaluator.
+
+No network is involved: playbooks are local files and job construction is pure.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+import pytest
+
+from src.scheduled_research.executor import next_due
+from src.scheduled_research.models import JobStatus, validate_schedule
+from src.scheduled_research.playbooks import (
+ PlaybookError,
+ PlaybookNotFoundError,
+ ResearchPlaybook,
+ build_job,
+ get_playbook,
+ list_playbooks,
+ load_playbook_file,
+ playbook_dirs,
+)
+from src.scheduled_research.store import ScheduledResearchJobStore
+
+EXPECTED_SLUGS = {
+ "a-share-money-flow",
+ "earnings-season-tracker",
+ "institutional-holdings-diff",
+ "portfolio-checkup",
+ "premarket-brief",
+}
+
+# 2026-08-04T12:00:00Z, fixed so first-fire assertions never depend on the clock.
+NOW_MS = 1785585600000
+
+_PLACEHOLDER_RE = re.compile(r"\{\{\s*[A-Za-z0-9_]+\s*\}\}")
+_SNAKE_CASE_RE = re.compile(r"\b[a-z]+(?:_[a-z0-9]+)+\b")
+
+
[email protected](autouse=True)
+def _no_user_playbook_dir(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Keep the bundled-catalogue assertions hermetic on a developer machine."""
+ monkeypatch.delenv("VIBE_TRADING_PLAYBOOK_DIR", raising=False)
+
+
+def _write(directory: Path, slug: str, text: str) -> Path:
+ directory.mkdir(parents=True, exist_ok=True)
+ path = directory / f"{slug}.md"
+ path.write_text(text, encoding="utf-8")
+ return path
+
+
+_MINIMAL = """---
+name: Minimal
+description: A minimal playbook.
+suggested_schedule: "3600000"
+data_capabilities:
+ - Daily closing prices for one symbol
+variables:
+ symbol: AAPL
+---
+
+# Minimal
+
+Look at {{symbol}}.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Bundled catalogue invariants
+# ---------------------------------------------------------------------------
+
+
+class TestBundledCatalogue:
+ def test_module_wins_over_same_named_data_directory(self) -> None:
+ """``playbooks.py`` and ``playbooks/`` coexist; the module must win."""
+ import src.scheduled_research.playbooks as module
+
+ assert module.__file__ is not None
+ assert Path(module.__file__).name == "playbooks.py"
+
+ def test_ships_the_expected_five(self) -> None:
+ assert {p.slug for p in list_playbooks()} == EXPECTED_SLUGS
+
+ def test_sorted_by_slug(self) -> None:
+ slugs = [p.slug for p in list_playbooks()]
+ assert slugs == sorted(slugs)
+
+ def test_covers_more_than_us_markets(self) -> None:
+ markets = {m for p in list_playbooks() for m in p.markets}
+ assert "cn" in markets and "global" in markets
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_suggested_schedule_is_valid(self, slug: str) -> None:
+ validate_schedule(get_playbook(slug).suggested_schedule)
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_suggested_timezone_resolves(self, slug: str) -> None:
+ tz = get_playbook(slug).suggested_timezone
+ if tz is None:
+ return
+ try:
+ ZoneInfo(tz)
+ except ZoneInfoNotFoundError: # host without a full IANA database
+ pytest.skip(f"host timezone database has no {tz!r}")
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_declares_data_capabilities_not_tool_names(self, slug: str) -> None:
+ playbook = get_playbook(slug)
+ assert playbook.data_capabilities
+ for capability in playbook.data_capabilities:
+ assert not _SNAKE_CASE_RE.search(capability), capability
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_body_names_no_tool(self, slug: str) -> None:
+ """Bodies describe capabilities; every tool in this repo is snake_case."""
+ body = _PLACEHOLDER_RE.sub("", get_playbook(slug).body)
+ assert not _SNAKE_CASE_RE.findall(body)
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_body_carries_the_missing_data_rule(self, slug: str) -> None:
+ body = get_playbook(slug).body
+ assert "## When data is missing" in body
+ assert "Data gaps" in body
+ assert "from memory" in body
+ assert "third-party summary" in body
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_body_states_output_and_boundaries(self, slug: str) -> None:
+ body = get_playbook(slug).body
+ assert "## Output" in body
+ assert "## Boundaries" in body
+ # Line wrapping must not decide whether the no-advice rule is present.
+ unwrapped = " ".join(body.split())
+ assert "No buy, sell, or hold calls" in unwrapped
+ assert "no price targets" in unwrapped
+ assert "Do not place, modify, or cancel any order" in unwrapped
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_body_resolves_the_run_date_at_run_time(self, slug: str) -> None:
+ """The prompt is stored once and replayed, so no date may be baked in."""
+ body = get_playbook(slug).body
+ assert "run environment" in body
+ assert not re.search(r"\b20\d\d-\d\d-\d\d\b", body)
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_renders_and_schedules(self, slug: str) -> None:
+ job = build_job(slug, now_ms=NOW_MS)
+ assert job.status is JobStatus.PENDING
+ assert "{{" not in job.prompt
+ assert job.next_run_at > NOW_MS # cron + timezone => first authored fire
+
+
+# ---------------------------------------------------------------------------
+# Loader
+# ---------------------------------------------------------------------------
+
+
+class TestLoader:
+ def test_parses_block_sequence_capabilities(self, tmp_path: Path) -> None:
+ path = _write(
+ tmp_path,
+ "multi",
+ "---\n"
+ "name: Multi\n"
+ "description: Two capabilities.\n"
+ 'suggested_schedule: "0 9 * * 1-5"\n'
+ "suggested_timezone: Asia/Shanghai\n"
+ "markets: [cn, hk]\n"
+ "data_capabilities:\n"
+ " - Prices, volumes and turnover for one session\n"
+ " - Sector rankings, including the laggards\n"
+ "---\n\nBody.\n",
+ )
+ playbook = load_playbook_file(path)
+ assert playbook.data_capabilities == (
+ "Prices, volumes and turnover for one session",
+ "Sector rankings, including the laggards",
+ )
+ assert playbook.markets == ("cn", "hk")
+ assert playbook.suggested_timezone == "Asia/Shanghai"
+
+ def test_slug_comes_from_the_filename(self, tmp_path: Path) -> None:
+ assert load_playbook_file(_write(tmp_path, "some-slug", _MINIMAL)).slug == "some-slug"
+
+ def test_defaults_markets_when_absent(self, tmp_path: Path) -> None:
+ assert load_playbook_file(_write(tmp_path, "m", _MINIMAL)).markets == ("global",)
+
+ def test_rejects_file_without_frontmatter(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "bare", "# Just a heading\n")
+ with pytest.raises(PlaybookError, match="frontmatter"):
+ load_playbook_file(path)
+
+ def test_rejects_non_mapping_frontmatter(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "seq", "---\n- a\n- b\n---\n\nBody.\n")
+ with pytest.raises(PlaybookError, match="must be a mapping"):
+ load_playbook_file(path)
+
+ def test_rejects_invalid_yaml(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "bad", "---\nname: [unclosed\n---\n\nBody.\n")
+ with pytest.raises(PlaybookError, match="not valid YAML"):
+ load_playbook_file(path)
+
+ def test_rejects_missing_required_key(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "nodesc", _MINIMAL.replace("description: A minimal playbook.\n", ""))
+ with pytest.raises(PlaybookError, match="description"):
+ load_playbook_file(path)
+
+ def test_rejects_invalid_schedule(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "badcron", _MINIMAL.replace('"3600000"', '"99 * * * *"'))
+ with pytest.raises(PlaybookError, match="out of range"):
+ load_playbook_file(path)
+
+ def test_rejects_empty_body(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "empty", _MINIMAL.split("# Minimal")[0].rstrip("\n") + "\n")
+ with pytest.raises(PlaybookError, match="body is empty"):
+ load_playbook_file(path)
+
+ def test_rejects_undeclared_placeholder(self, tmp_path: Path) -> None:
+ path = _write(tmp_path, "typo", _MINIMAL.replace("{{symbol}}", "{{symbal}}"))
+ with pytest.raises(PlaybookError, match="undeclared variables"):
+ load_playbook_file(path)
+
+ def test_rejects_empty_capability_entry(self, tmp_path: Path) -> None:
+ path = _write(
+ tmp_path,
+ "blank",
+ _MINIMAL.replace(" - Daily closing prices for one symbol\n", ' - ""\n'),
+ )
+ with pytest.raises(PlaybookError, match="empty entry"):
+ load_playbook_file(path)
+
+
+# ---------------------------------------------------------------------------
+# Lookup and directory precedence
+# ---------------------------------------------------------------------------
+
+
+class TestLookup:
+ def test_unknown_slug_lists_available(self) -> None:
+ with pytest.raises(PlaybookNotFoundError, match="premarket-brief"):
+ get_playbook("does-not-exist")
+
+ @pytest.mark.parametrize("slug", ["../models", "a/b", "Upper", "", "a b"])
+ def test_rejects_malformed_slug(self, slug: str) -> None:
+ with pytest.raises(PlaybookNotFoundError, match="invalid playbook slug"):
+ get_playbook(slug)
+
+ def test_env_directory_is_searched_first(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))
+ assert playbook_dirs()[0] == tmp_path
+
+ def test_user_file_shadows_bundled_slug(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ _write(tmp_path, "premarket-brief", _MINIMAL)
+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))
+ assert get_playbook("premarket-brief").name == "Minimal"
+ catalogue = {p.slug: p.name for p in list_playbooks()}
+ assert catalogue["premarket-brief"] == "Minimal"
+ assert set(catalogue) == EXPECTED_SLUGS # override, not addition
+
+ def test_missing_directory_is_not_an_error(self, tmp_path: Path) -> None:
+ assert list_playbooks(directory=tmp_path / "nope") == []
+
+ def test_broken_user_file_surfaces_instead_of_being_skipped(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ _write(tmp_path, "broken", "no frontmatter here\n")
+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))
+ with pytest.raises(PlaybookError, match="frontmatter"):
+ list_playbooks()
+
+ def test_every_listed_slug_is_retrievable(self) -> None:
+ """The catalogue must never advertise an entry get_playbook refuses."""
+ for playbook in list_playbooks():
+ assert get_playbook(playbook.slug).slug == playbook.slug
+
+ @pytest.mark.parametrize("stem", ["My_Playbook", "Upper", "has space", "under_score"])
+ def test_badly_named_file_is_rejected_at_load(self, tmp_path: Path, stem: str) -> None:
+ """A file whose stem is not a valid slug fails loudly instead of
+ becoming a catalogue entry that get_playbook can never return."""
+ path = _write(tmp_path, stem, _MINIMAL)
+ with pytest.raises(PlaybookError, match="not a valid slug"):
+ load_playbook_file(path)
+ with pytest.raises(PlaybookError, match="not a valid slug"):
+ list_playbooks(directory=tmp_path)
+
+ def test_utf8_bom_does_not_hide_the_frontmatter(self, tmp_path: Path) -> None:
+ """A BOM from a Windows editor must not read as 'missing frontmatter'."""
+ path = tmp_path / "bom.md"
+ path.write_text(_MINIMAL, encoding="utf-8-sig")
+ assert load_playbook_file(path).name == "Minimal"
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+class TestRender:
+ def _minimal(self, tmp_path: Path) -> ResearchPlaybook:
+ return load_playbook_file(_write(tmp_path, "minimal", _MINIMAL))
+
+ def test_uses_declared_defaults(self, tmp_path: Path) -> None:
+ assert self._minimal(tmp_path).render() == "# Minimal\n\nLook at AAPL."
+
+ def test_override_wins(self, tmp_path: Path) -> None:
+ assert "600519.SH" in self._minimal(tmp_path).render({"symbol": "600519.SH"})
+
+ def test_blank_override_falls_back_to_default(self, tmp_path: Path) -> None:
+ assert "AAPL" in self._minimal(tmp_path).render({"symbol": " "})
+
+ def test_undeclared_variable_is_an_error(self, tmp_path: Path) -> None:
+ with pytest.raises(PlaybookError, match="has no variable"):
+ self._minimal(tmp_path).render({"ticker": "AAPL"})
+
+ def test_oversized_value_is_rejected(self, tmp_path: Path) -> None:
+ with pytest.raises(PlaybookError, match="the cap is"):
+ self._minimal(tmp_path).render({"symbol": "A" * 4001})
+
+ def test_braces_in_a_value_are_not_re_expanded(self, tmp_path: Path) -> None:
+ rendered = self._minimal(tmp_path).render({"symbol": "{{symbol}}"})
+ assert rendered.endswith("Look at {{symbol}}.")
+
+
+# ---------------------------------------------------------------------------
+# Job construction
+# ---------------------------------------------------------------------------
+
+
+class TestToJob:
+ def test_defaults_to_the_suggested_cadence(self) -> None:
+ playbook = get_playbook("premarket-brief")
+ job = playbook.to_job(now_ms=NOW_MS)
+ assert job.schedule == playbook.suggested_schedule
+ assert job.timezone == playbook.suggested_timezone
+ assert job.id.startswith("playbook-premarket-brief-")
+ assert job.created_at == NOW_MS
+
+ def test_first_fire_matches_the_cron_evaluator(self) -> None:
+ playbook = get_playbook("a-share-money-flow")
+ job = playbook.to_job(now_ms=NOW_MS)
+ assert job.next_run_at == next_due(
+ playbook.suggested_schedule, NOW_MS, playbook.suggested_timezone
+ )
+
+ def test_interval_schedule_fires_immediately(self) -> None:
+ job = get_playbook("premarket-brief").to_job(schedule="3600000", now_ms=NOW_MS)
+ assert job.schedule == "3600000"
+ assert job.next_run_at == NOW_MS
+
+ def test_explicit_none_timezone_means_utc_and_immediate_first_fire(self) -> None:
+ job = get_playbook("premarket-brief").to_job(timezone=None, now_ms=NOW_MS)
+ assert job.timezone is None
+ assert job.next_run_at == NOW_MS
+
+ def test_explicit_next_run_at_wins(self) -> None:
+ job = get_playbook("premarket-brief").to_job(next_run_at=42, now_ms=NOW_MS)
+ assert job.next_run_at == 42
+
+ def test_rejects_a_malformed_schedule_override(self) -> None:
+ with pytest.raises(ValueError, match="cron"):
+ get_playbook("premarket-brief").to_job(schedule="not a schedule")
+
+ def test_rejects_an_unresolvable_timezone_override(self) -> None:
+ with pytest.raises(ValueError, match="not a recognized IANA timezone"):
+ get_playbook("premarket-brief").to_job(timezone="Mars/Olympus")
+
+ def test_prompt_is_the_rendered_body(self) -> None:
+ playbook = get_playbook("portfolio-checkup")
+ variables = {"holdings": "600519.SH 100; AAPL 50"}
+ job = playbook.to_job(variables=variables, now_ms=NOW_MS)
+ assert job.prompt == playbook.render(variables)
+ assert "600519.SH 100; AAPL 50" in job.prompt
+
+ def test_config_records_provenance_but_never_overwrites_the_caller(self) -> None:
+ assert build_job("premarket-brief", now_ms=NOW_MS).config == {"playbook": "premarket-brief"}
+ job = build_job("premarket-brief", now_ms=NOW_MS, config={"playbook": "mine", "model": "x"})
+ assert job.config == {"playbook": "mine", "model": "x"}
+
+ def test_caller_config_is_copied_not_aliased(self) -> None:
+ supplied: dict = {}
+ build_job("premarket-brief", now_ms=NOW_MS, config=supplied)
+ assert supplied == {}
+
+ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))
+ def test_job_survives_the_real_store(self, tmp_path: Path, slug: str) -> None:
+ store = ScheduledResearchJobStore(tmp_path / "jobs.json")
+ job = build_job(slug, now_ms=NOW_MS)
+ store.upsert(job)
+ loaded = store.get(job.id)
+ assert loaded is not None
+ assert loaded.prompt == job.prompt
+ assert loaded.schedule == job.schedule
+ assert loaded.timezone == job.timezone
+
+
+# ---------------------------------------------------------------------------
+# Catalogue serialization
+# ---------------------------------------------------------------------------
+
+
+class TestToDict:
+ def test_omits_the_body_by_default(self) -> None:
+ data = get_playbook("premarket-brief").to_dict()
+ assert "body" not in data
+ assert data["slug"] == "premarket-brief"
+ assert isinstance(data["data_capabilities"], list)
+ assert isinstance(data["markets"], list)
+ assert data["variables"]["home_market"]
+
+ def test_includes_the_body_on_request(self) -> None:
+ assert get_playbook("premarket-brief").to_dict(include_body=True)["body"]
+
+ def test_every_bundled_record_is_json_serializable(self) -> None:
+ import json
+
+ json.dumps([p.to_dict(include_body=True) for p in list_playbooks()])
diff --git a/pyproject.toml b/pyproject.toml
index 355cc7882..e97782f13 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -90,6 +90,7 @@ include = ["src*", "backtest*", "cli*"]
"skills/**/*.json",
"skills/**/*.py",
"providers/*.json",
+ "scheduled_research/playbooks/*.md",
"swarm/presets/*.yaml",
"shadow_account/templates/*.j2",
"shadow_account/templates/*.html",