Record the four schema and naming decisions: rename, pattern capture groups, null placement, dtype sweep

[mmcky]

Writes the four decisions ratified on 2026-09-07 into the tree, so the shared manifest-driven validate() (#119) has a spec to read rather than a strawman. No data bytes change: the one renamed CSV hashes to the sha256 its manifest records, and check_consumed_files.py passes locally (44 manifests, 47 files hash-checked, 0 errors).

What changes

Decision	Edit
#113 naming policy	business_cycle_data.csv → gdp_growth_annual.csv (file + sidecar), renamed while consumers: []. The six rules are the comment beside filename in manifest-schema.yml and a paragraph in AGENTS.md. Every reference follows: builders/business_cycle.py (TABLES entry and docstring), builders/README.md, the migration.yml key, PLAN.md, scripts/render_audit.py, scripts/audit_annotations.yml, and CATALOG.md regenerated. The two sibling manifests drop their "FILENAME IS PROVISIONAL" headers.
#120 pattern semantics	YR\d{4} → YR(\d{4}) in the three World Bank manifests; the capture group is what the validator derives date_range from. Full-match, ordered, contiguous, at least one match, exhaustive — recorded as the comment on pattern.
#121 nulls	Integers under known_nulls stay exact. The four dynamic snapshots gain a nulls: placement block (along, leading, recent, ended, inner) that mirrors what business_cycle.py and business_cycle_fred.py already assert by hand. known_nulls_total leaves the two named-column manifests that used it as a ceiling; it stays legal only inside header: null sheet reads (assignat.xlsx, dette.xlsx), where there are no column names to count against — a correction to the #121 comment, recorded there.
#122 dtype vocabulary	21 string + 9 object → str, 2 datetime → datetime64, forbes government str → bool (it is a boolean column with 2606 nulls). The closed list and the compare-by-family rule are the comment on dtype.

Two things for the #119 implementer

YAML reads the period scalars in nulls.inner back as datetime.date, the same trap snapshots.py stamp already guards against for date_range.end — compare as text. And the validator reads the raw file with pandas defaults (honouring delimiter and read_as, no index_col, parse_dates derived from datetime64 declarations); the manifest describes the bytes on disk, not the frame a lecture builds. Both are now stated at the top of the schema block in manifest-schema.yml.

Verification

• All 44 manifests, manifest-schema.yml and migration.yml parse; every dynamic snapshot carries a nulls block; every manifest's filename matches its sidecar name.
• scripts/snapshots.py list reports the four snapshots under their current names.
• python scripts/build_catalog.py regenerated CATALOG.md (one row changed).
• Nothing reads the manifests' pattern, nulls or dtype yet — the builders keep their own constants until Manifest-driven validate(): read the sidecar schema block as the spec, shared by builders and a PR-validation workflow #119 lands — so no runtime behaviour changes in this PR.

Unblocks block B of #118 (the lecture-wasm adoption, QuantEcon/lecture-wasm#70), since the filenames are now frozen.

Closes #120. Closes #121. Closes #122. Closes #113.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

A few documentation inconsistencies remain (including a future-dated policy label, a contradictory dtype description, and a stale reference to the old sidecar path) that should be corrected before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates repository-wide documentation and manifest schema conventions to reflect ratified decisions around dataset naming and the executable schema contract, including a dataset rename from business_cycle_data.csv to gdp_growth_annual.csv and related reference updates.

Changes:

• Renames the dynamic snapshot dataset to gdp_growth_annual.csv (CSV + sidecar manifest) and updates internal references (builder, migration tracker, audit text, catalog).
• Records schema-contract decisions in manifest-schema.yml (pattern capture groups, null placement rules, dtype vocabulary/family comparisons) and propagates them across manifests.
• Normalizes manifest dtype declarations (e.g., object/string/datetime → str/datetime64) and adds explicit nulls: placement blocks to dynamic snapshots.

File summaries

File	Description
scripts/render_audit.py	Updates audit rules text to reference gdp_growth_annual.csv.
scripts/audit_annotations.yml	Updates annotation note to reflect renamed snapshot filename.
PLAN.md	Updates plan narrative to note the rename and related policy references.
migration.yml	Rekeys the dataset entry to gdp_growth_annual.csv and documents the rename rationale.
manifest-schema.yml	Records naming + schema execution decisions (patterns, null placement, dtype vocabulary).
lectures/gdp_growth_annual.csv	Adds the renamed GDP growth dataset under the new filename.
lectures/gdp_growth_annual.csv.yml	Renames/updates the GDP growth sidecar manifest (pattern capture group + null placement).
lectures/unemployment_rate_annual.csv.yml	Updates pattern to capture-group form and adds nulls: placement rule.
lectures/private_credit_to_gdp.csv.yml	Updates pattern to capture-group form and adds nulls: placement rule.
lectures/us_business_cycle_monthly.csv.yml	Updates dtype to datetime64, refines null handling into exact-count + placement rule form.
lectures/fred_data.csv.yml	Normalizes DATE dtype to datetime64.
lectures/forbes-billionaires.csv.yml	Changes government dtype to bool and updates description.
lectures/us_adult_heights.csv.yml	Normalizes dtype from object to str.
lectures/test_pwt.csv.yml	Normalizes dtype from object to str.
lectures/realwage.csv.yml	Normalizes dtype from string to str.
lectures/japan_earthquakes.csv.yml	Normalizes dtype from object to str.
lectures/epl_match_goals.csv.yml	Normalizes dtype from object to str.
lectures/employ.csv.yml	Normalizes dtype from string to str.
lectures/countries.csv.yml	Normalizes dtype from string to str.
lectures/ames_house_prices.csv.yml	Normalizes dtype from object to str.
builders/README.md	Updates builder coverage table to reflect the renamed GDP growth file.
builders/business_cycle.py	Updates TABLES entry and docs to output gdp_growth_annual.csv.
AGENTS.md	Records naming and schema-contract decisions at the repo guidance level.
CATALOG.md	Regenerates catalog to reflect renamed dataset entry.

Review details

• Files reviewed: 23/24 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.