=== RESEARCH ===
{'issue': 301, 'kind': 'docs', 'defect_status': 'confirmed', 'category': 'api-restructure', 'target_files': ['docs/src/api.md', 'docs/src/api_types.md', 'docs/src/api_functions.md', 'docs/make.jl', 'docs/src/index.md'], 'summary': 'Split the 3 monolithic API-reference pages into per-domain api/*.md pages, replace the hand-drawn type-hierarchy trees with an @eval subtypes() block, and (only after the docstring backlog is registered) drop :missing_docs from make.jl warnonly.', 'current_state': 'Defect is fully present at release/v0.6.6 tip. (1) There is NO docs/src/api/ subdirectory — the reference is still 3 hand-maintained pages: api.md (index, 27761 B), api_types.md (581 lines), api_functions.md (979 lines). (2) Hand-drawn ASCII type trees are still in api_types.md:315-467 (the "## Type Hierarchy" block), including the stale AbstractUnitRootTest tree at api_types.md:402-408 flagged by §4.6. (3) The plotting @autodocs Pages list at api_functions.md:835 omits "plotting/spectral.jl" even though src/plotting/spectral.jl exists (T192 item 2). (4) make.jl:100-104 still registers Overview=api.md / Types=api_types.md / Functions=api_functions.md; index.md:307 @contents still lists api.md, api_types.md, api_functions.md. (5) make.jl:110 warnonly=[:missing_docs, :cross_references] — :missing_docs still silenced. CRITICAL GATE: the HA/OLG/CT surface is documented NOWHERE — dsge_ha.md, dsge_olg.md, dsge_continuous.md each contain 0 @docs/@autodocs blocks and no HA/OLG/CT name appears in any api page (grep for heterogeneous|krusell|aiyagari|olg|continuous returns nothing). So #276 (T177) / #277 (T178) are NOT complete; dropping :missing_docs today would turn CI red on every HA/OLG/CT export.', 'proposed_change': 'Execute in three separable parts; parts A/B are docs-quality and can land in v0.6.7, part C is GATED (see dependencies).\n\nPART A — per-domain split (structural): Create docs/src/api/ with one page per sidebar domain: univariate.md, multivariate.md, cross_section.md, panel.md, dsge.md, structural.md, nowcasting.md, gmm.md, io.md, tests.md, visualization.md (mirror the make.jl:24-104 sidebar sections). Move every @docs/@autodocs block out of api_types.md and api_functions.md into the matching domain page, keeping the existing convention: @docs where the source filename substring-matches, @autodocs Modules=[MacroEconometricModels] Pages=[...] otherwise. Each export must land on exactly one page. When splitting, ALSO register the currently-missing HA/OLG/CT/IO surface onto api/dsge.md and api/io.md (coordinate with #276). Fix the plotting @autodocs on api/visualization.md by adding "plotting/spectral.jl" to the Pages list currently at api_functions.md:835 (subsumes T192/#291 item 2). Delete api_functions.md and api_types.md after their blocks are relocated.\n\nPART B — @eval type hierarchy (subsumes T192/#291 item 1): Delete the hand-drawn "## Type Hierarchy" ASCII block (api_types.md:315-467). Replace with an @eval block that walks subtypes() from the package\'s abstract roots. The abstract roots in source (grep \'abstract type\' src/, re-derive at implementation time): AbstractMacroData, AbstractARIMAModel, AbstractVARModel, AbstractAnalysisResult, AbstractFrequentistResult, AbstractBayesianResult, AbstractImpulseResponse, AbstractLPImpulseResponse, AbstractFEVD, AbstractHistoricalDecomposition, AbstractFactorModel, AbstractLPModel, AbstractCovarianceEstimator, AbstractGMMModel, AbstractPrior, AbstractUnitRootTest, AbstractNormalityTest, AbstractNonGaussianSVAR, AbstractVolatilityModel, AbstractNowcastModel, AbstractDSGEModel, AbstractForecastResult, AbstractFilterResult, DSGEConstraint, MacroModelError (25 roots — re-derive the exact list from src at build time so it can never drift). Put the rendered tree on api.md (the domain index) or a dedicated api/types.md.\n\nPART C — enforce checkdocs (GATED): ONLY after #276 (T177) and #277 (T178) have landed and a full build shows zero :missing_docs warnings, edit make.jl:110 to warnonly=[:cross_references] (remove :missing_docs). Do NOT do this in the same PR as parts A/B unless the HA/OLG/CT/IO/17-undocumented backlog is already green.\n\nWIRING (must accompany part A): make.jl:100-104 — replace the "API Reference" => [Overview/Types/Functions] block with one entry per new api/*.md page. index.md:307 @contents — replace the "api.md","api_types.md","api_functions.md" tail with the new api/*.md page list. api.md survives as the domain index; verify every quick-reference table row links to its owning narrative page (api.md already links via (data.md) style refs — audit criterion, spot-check all sections).\n\nNOTE for implementer: the acceptance criterion "Follow docrule.md Reference page type / Cross-Reference Requirements / build-config invariants" references sections that do NOT exist in the current docs/docrule.md (its headings are Page Anatomy, Quick Start, Code Block Types, References, Formatting, Anti-Patterns, Verification — no "Reference" page-type and no "Cross-Reference Requirements" section). Treat that criterion as satisfied by the existing api-page convention, or coordinate with #278 (T179 docrule/config drift) if a Reference page-type section is being added.', 'verify': 'Planning only — do NOT run here. Implementer gate: `julia --project=docs docs/make.jl` (full makedocs; @docs/@autodocs registration and @eval subtypes() are only exercised by makedocs, NOT by verify_examples). Build must be green with checkdocs=:exports; after Part C, green with :missing_docs removed from warnonly. Per-page example smoke check where a page carries @example blocks: `julia --project=docs docs/verify_examples.jl docs/src/api/<page>.md` (most api pages are @docs-only, so verify_examples is a no-op there — makedocs is the real gate).', 'dependencies': [276, 277, 108], 'collisions': ['docs/make.jl — #108 (T009 also edits the warnonly list — direct conflict with Part C)', 'docs/make.jl — #295 (T196 restructures the pages= nav; must merge the new api/*.md entries)', 'docs/make.jl — #278 (T179 edits make.jl build-config/size_threshold)', 'docs/make.jl — #276 (T177 may register exports touching make.jl/pages)', 'docs/src/api_types.md — #291 (T192 fixes the exact type-tree at :402-410 this issue deletes)', 'docs/src/api_functions.md — #291 (T192 fixes plotting/spectral.jl at :834 this issue also fixes)', 'docs/src/api_types.md — #276 (T177 registers HA/CT/OLG types into api pages)', 'docs/src/api_functions.md — #276 (T177 registers HA/CT/OLG functions into api pages)', 'docs/src/index.md — #295 (T196 edits the @contents/nav)'], 'effort': 'L', 'risk': 'high'}

=== VERIFY ===
{'issue': 301, 'verdict': 'CORRECTED', 'assessment': "Every factual claim in the spec is confirmed against the current tree (release/v0.6.6 tip). No docs/src/api/ subdir (ls: No such file or directory). api.md is 27761 B exactly; api_types.md 580 lines, api_functions.md 978 lines (1-line drift from cited 581/979, immaterial — the cited line regions are exact). Type Hierarchy heading at api_types.md:315, ASCII fence 317-467; stale AbstractUnitRootTest subtree at api_types.md:402-408 (genuinely incomplete: teststat/ ships dfgls/fourier/adf_2break/gregory_hansen/lm_unitroot/stationarity result types not in the tree). Plotting @autodocs at api_functions.md:833-835 lists 9 plotting files and omits plotting/spectral.jl, which exists (14203 B) and defines plot_result dispatches — omission confirmed (matches audit report line 354). make.jl:100-104 Overview/Types/Functions; make.jl:106 checkdocs=:exports; make.jl:110 warnonly=[:missing_docs,:cross_references]; index.md:307 @contents tail lists the 3 api pages. CRITICAL GATE confirmed: HA/OLG/CT symbols are EXPORTED (HASteadyState, HADSGESolution, KrusellSmithSolution, DenHaanAccuracy, BlanchardOLG*, CTAiyagari/CTPoissonIncome/CTSteadyState/CTTransition) yet appear in zero @docs/@autodocs blocks and no api page — so removing :missing_docs would error the docs build on every such export; #276/#277 are not complete. docrule.md headings confirm the NOTE (no Reference page-type / Cross-Reference Requirements sections). Two corrections needed, below. Overall defect real; Parts A/B/C are the right plan; Part B's seed set and one rationale sentence need fixing.", 'corrections': 'PART B — the enumerated 25 "abstract roots" are NOT all roots. Reading `abstract type` declarations with supertypes in src/, 6 are nested under other package abstracts: AbstractBayesianResult, AbstractFEVD, AbstractFrequentistResult, AbstractHistoricalDecomposition and AbstractImpulseResponse are all `<: AbstractAnalysisResult`; AbstractLPImpulseResponse is `<: AbstractImpulseResponse`. An @eval that iterates all 25 calling subtypes() and printing each subtree would render those 6 subtrees TWICE (once nested, once as a bogus top-level root). Fix: seed the walk ONLY from true top-level roots — abstracts whose supertype is Any, an external StatsAPI type, or Exception — i.e. the 19 roots = the 25 minus those 6, then recurse via subtypes(); OR compute the full abstract set and dedupe so each abstract prints once. Re-derive true-roots at build time by filtering `t` where `supertype(t)` is not itself a package abstract (this is what "re-derive from src so it can never drift" must actually mean here).\n\nRATIONALE NIT (non-blocking, does not change any implementer action; Part C is gated regardless): the current_state phrase "dropping :missing_docs today would turn CI red on every HA/OLG/CT export" is stale — make.jl:113-116 documents that docs were removed from CI on 2026-07-10 (Documentation.yml deleted) and are now built manually via docs/deploy_local.jl. The gate is still valid, but the failure surface is the MANUAL/local build, not CI.\n\nEverything else stands as written: Part A per-domain split + adding plotting/spectral.jl to the visualization @autodocs Pages list + deleting the ASCII Type Hierarchy block is correct; Part C correctly gated on #276/#277.', 'collision_issues': [291, 276, 277, 295, 278, 108], 'discriminating_power': 'n/a (docs-only issue; no test assertions involved)', 'final_effort': 'L'}