=== RESEARCH ===
{'issue': 289, 'kind': 'docs', 'defect_status': 'confirmed', 'category': 'docs-med-sweep', 'target_files': ['docs/src/dsge.md', 'docs/src/dsge_linear.md', 'docs/src/dsge_olg.md', 'docs/src/dsge_continuous.md', 'docs/src/dsge_ha.md', 'docs/src/dsge_hd.md', 'CLAUDE.md'], 'summary': "Seven-part MED sweep of the nine DSGE doc pages: fix the Dynare model count (27→24) and solve() method count (7→8) with a single owning 8-method table, add the three missing hub child links, de-static the Quick-Start recipes, mature the OLG/CT pages (keyword+return tables, admonitions, no println-for-results, unqualified exported calls, CT Complete Example), drop the ha config println, and move dsge_hd's trailing @docs block above References.", 'current_state': 'All 7 sub-defects still present in the working tree (release/v0.6.6 tip). (1) dsge.md:14 and :387 say "27-model" / "27-model replication suite"; the tier table dsge.md:398-406 lists 24 models and `test/dynare_replication/` has exactly 24 tier*.jl scripts (14 tier1 + 4 tier2 + 2 tier3 + 2 tier4 + 1 tier5 + 1 tier6) plus 3 support files (estimation_sw07.jl, helpers.jl, sw07_model.jl) = 27 .jl files; CLAUDE.md:244 still says "22 models". (2) dsge.md:3 says "seven solution methods"; `solve()` at src/dsge/gensys.jl:196 dispatches 8: :gensys(206), :blanchard_kahn(253), :perfect_foresight(257), :klein(259), :perturbation(263), :projection(266), :pfi(268), :vfi(270) — error msg lists all 8 at :273. dsge_linear.md:74-82 method table lists 7, OMITS :vfi while including :perfect_foresight. (3) dsge.md feature bullets link dsge_linear/nonlinear/constraints/estimation/hd_page but never dsge_ha/dsge_olg/dsge_continuous (anchors: dsge_ha.md:1 @id dsge_ha, dsge_olg.md:1 @id dsge_olg, dsge_continuous.md:1 @id dsge_continuous). (4) dsge.md recipes 3 (:88-94), 4 (:96-107), 6 (:118-127) are static ```julia blocks whose report()/plot_result() outputs the reader should see, with undefined vars (Y_data, shocks, R, data) — anti-pattern no.12. (5) dsge_olg.md: 0 admonitions, 0 keyword tables, no return table for blanchard_solve/blanchard_transition, and println for results at :117 (\'println("b = ",b," → r = ",...)\'). dsge_continuous.md: NO "## Complete Example" section, keyword table only for ct_mit_shock (:133-138) — none for ct_steady_state/ct_two_asset_solve, CTTwoAssetSolution return table (:167-173) lists 6 of 12 fields, and ct_hjb/ct_kfe called module-qualified at :60/:75 though both are exported (src/MacroEconometricModels.jl:539). (6) dsge_ha.md:461-467 @example loops println(rpad(name,20),...) to display configs duplicating the table at :453-458 (anti-pattern no.1). (7) dsge_hd.md ends with a ```@docs block (historical_decomposition, dsge_smoother, dsge_particle_smoother, KalmanSmootherResult) AFTER "## References", violating docrule.md:60 "Every page ends with a References section."', 'proposed_change': 'Edit each page; re-locate anchors by grep (lines above are current). CAVEAT: the issue cites docrule sections that do NOT exist in the current docrule.md — there is no "§Tables owning-page rule", no "§Code Block Types", no "Hub skeleton" page-type, and the anti-pattern list has only 12 items (no "no.18"). The revised docrule is being introduced by sibling issue #294 (T195). The defects are still valid, backed by docrule.md:60 (page ends on References), anti-pattern no.1 (:370, println), anti-pattern no.10 (:376, duplicated content → cross-reference), anti-pattern no.12 (:377, static julia for output), and the standard skeleton (docrule.md:9-52). Cite those, not the phantom sections.\n\n(1) DYNARE COUNT → 24. In dsge.md change ":14" "27-model replication suite" → "24-model replication suite" and ":387" "The package includes a 27-model replication suite" → "24-model". Tier table (:398-406) already sums to 24 — leave numbers, no change. In CLAUDE.md change ONLY line 244 ("Dynare replication suite: 22 models with SS/IRF/VD/moments comparison") → "24 models". Do NOT touch CLAUDE.md:328/:330 — those are dated v0.5.0 historical release notes ("(22 models)") and must stay historically accurate. Source of truth: 24 tier*.jl scripts under test/dynare_replication/ (do not count estimation_sw07.jl/helpers.jl/sw07_model.jl as models).\n\n(2) SOLVE() METHODS → one owning 8-method table on dsge.md. Change dsge.md:3 "seven solution methods" → "eight solution methods". Put the complete accepted-methods table on the dsge.md hub (recommended location: in/after "## Complete Example" or a new short "## Solution Methods" H2), listing all 8 with the exact method symbols and one-line algorithm+reference each, sourced from src/dsge/gensys.jl:206-274: :gensys (Sims 2002 QZ, default), :blanchard_kahn (Blanchard & Kahn 1980), :klein (Klein 2000 generalized Schur), :perfect_foresight (deterministic Newton), :perturbation (order 1-3, Schmitt-Grohe & Uribe 2004), :projection (Chebyshev collocation, Judd 1998), :pfi (policy function iteration), :vfi (value function iteration). Then in dsge_linear.md replace the 7-row table at :74-82 with the three LINEAR methods only (:gensys/:blanchard_kahn/:klein, which is what that page covers per its :84 sentence) and add a cross-reference line "For the full set of eight `solve()` methods see [DSGE Models](@ref dsge_page)." This removes the partial/contradictory list (the :vfi omission) by scoping the linear page to its 3 methods and pointing to the hub for the complete set (docrule anti-pattern no.10).\n\n(3) HUB CHILD LINKS. In dsge.md add linked entries for the three orphaned children. Simplest: append to the feature bullet list (:5-14) or the "Complete Example"/method area three bullets: "- **Heterogeneous Agents**: ... see [Heterogeneous Agent DSGE](@ref dsge_ha)", "- **Overlapping Generations**: Blanchard (1985) perpetual youth; see [Overlapping Generations](@ref dsge_olg)", "- **Continuous Time**: Achdou et al. (2022) HJB/KFE HA models; see [Continuous Time](@ref dsge_continuous)". Anchors verified at each child\'s line 1. NOTE: #294 (T195) will re-shape dsge.md into the Hub skeleton and reuses this fix — keep the anchors correct so T195 inherits them.\n\n(4) STATIC RECIPES. Cheapest low-risk fix (estimation is too slow to run at doc-build): keep recipes 3/4/6 as static ```julia but STRIP the output-producing trailing calls so they become pure API-signature blocks (allowed by anti-pattern no.12): recipe 3 (:90-94) drop `report(est)`; recipe 6 (:120-127) drop `report(result)`; recipe 4 (:98-107) keep the `plot_result(occ_irf)`+@raw-html iframe (plot_result static is allowed) but the occbin_solve/occbin_irf calls reference undefined `shocks`/model-with-`R` — either add a one-line comment framing them as illustrative signatures or provide an NK @setup with an R equation. Alternative (higher cost) per issue: wrap in @example with a real @setup — NOT recommended (GMM/SMC² build cost). Because #294 (T195) will trim the hub\'s Quick Start to ONE recipe, coordinate: the minimal signature-only fix here is forward-compatible.\n\n(5a) OLG maturation (dsge_olg.md). Add a keyword table for the `BlanchardOLG(; ...)` constructor, sourced from src/olg/blanchard.jl:64-65: alpha `Real` `0.36` capital share; beta `Real` `0.96` discount factor; delta `Real` `0.08` depreciation; gamma `Real` `0.98` survival probability (1 = Ramsey); Z `Real` `1.0` TFP; b `Real` `0.0` per-capita govt debt. Add a return table for `blanchard_solve` (returns BlanchardOLGSolution, blanchard.jl:99-106): ss `BlanchardOLGSteadyState`, M `Matrix{T}` 2×2 linearized transition, eigenvalues `Vector{ComplexF64}`, stable_eig `T` saddle-path eigenvalue, policy_slope `T` dC/dk, determinate `Bool`. Add a return table for `blanchard_transition` (returns NamedTuple, blanchard.jl:264,281; kwarg H::Int=50): k/C/r/w each `Vector{T}` of length H+1. Add at least one admonition (e.g. !!! note on the log-utility / fair-annuity assumption or the high-capital-root selection, placed before the relevant code per docrule:311 "before the code"). Replace the println loop at :114-119 with a rendered result: build a NamedTuple/collect into a table (e.g. per-b (r,k) tuples in a comprehension shown as the block\'s last expression) — no println for results (docrule anti-pattern no.1).\n\n(5b) CT maturation (dsge_continuous.md). Unqualify exported calls: :60 `MacroEconometricModels.ct_hjb(m, r, w)` → `ct_hjb(m, r, w)`; :75 `MacroEconometricModels.ct_kfe(A, m.I, da)` → `ct_kfe(A, m.I, da)` (both exported at src/MacroEconometricModels.jl:539). Add keyword tables: for `ct_steady_state` (continuous_aiyagari.jl:266-270): r_bounds `Tuple{Real,Real}` `(0.0001, ρ-1e-4)`, max_iter `Int` `100`, tol `Real` `1e-6`, hjb_max_iter `Int` `100`, hjb_tol `Real` `1e-6`, Delta `Real` `1000.0`; for `ct_two_asset_solve` (two_asset.jl:224-225): max_iter `Int` `200`, tol `Real` `1e-6`, Delta `Real` `1000.0`. (Optionally add CTAiyagari/CTTwoAsset constructor keyword tables from continuous_aiyagari.jl:67-70 and two_asset.jl:67-70.) Complete the CTTwoAssetSolution return table (:167-173, currently B,A,g,c,d,gen) to all 12 public fields from src/ct/two_asset.jl:87-100: b `Vector{T}` liquid grid, a `Vector{T}` illiquid grid, V `Array{T,3}` value, c `Array{T,3}` consumption, d `Array{T,3}` deposit, sb `Array{T,3}` liquid saving drift, sa `Array{T,3}` illiquid saving drift, g `Array{T,3}` joint density, B `T` aggregate liquid, A `T` aggregate illiquid, gen `SparseMatrixCSC{T}` generator, hjb_converged `Bool`. Add a "## Complete Example" H2 near the end (before Common Pitfalls, docrule:59) — a full one-asset CTAiyagari worked example (ct_steady_state + report + a couple of interpreted field-access lines). NOTE: #294 (T195) item 3 states this CT Complete Example also satisfies its Method-page retrofit — build it here so T195 just confirms.\n\n(6) dsge_ha.md println. Delete the @example block at :460-468 (the for-loop with println(rpad(name,20),...)) entirely — the table at :453-458 already conveys the same config info (docrule anti-pattern no.1 + no.10). Keep the surrounding prose (:451 intro, :470 interpretation).\n\n(7) dsge_hd.md @docs placement. Move the trailing ```@docs block (historical_decomposition, dsge_smoother, dsge_particle_smoother, KalmanSmootherResult) to BEFORE the "## References" section so the page ends on References (docrule.md:60). These four symbols are NOT @docs\'d in api_functions.md/api_types.md, so no duplicate-docstring error is introduced. (The other DSGE pages carry no @docs block at all; if the release prefers full consistency, an alternative is to relocate these into api_functions.md/api_types.md and drop the block — but the issue\'s directive is the in-page move, which is lower-risk.)', 'verify': 'Per edited doc page: `julia --project=docs docs/verify_examples.jl docs/src/dsge.md`, and likewise for dsge_linear.md, dsge_olg.md, dsge_continuous.md, dsge_ha.md, dsge_hd.md → each must print OK. CLAUDE.md is not doc-built (no verify). The dsge_olg.md/dsge_continuous.md edits add/execute new @example blocks (CT Complete Example, OLG rendered tables) so those two are the most likely to surface build errors — run them first. Optionally a full `julia --project=docs docs/make.jl` to confirm the new @ref hub links and the moved @docs block resolve without Documenter cross-reference/duplicate errors.', 'dependencies': [], 'collisions': ['docs/src/dsge.md — #294 (T195 hub retrofit; depends on this issue for the child links, will reshape Quick Start to ONE recipe and add the method-comparison/decision table — coordinate the 8-method table and recipe de-statification so T195 inherits them)', "docs/src/dsge_continuous.md — #294 (T195 explicitly reuses this issue's CT '## Complete Example' as its Method-page retrofit)", 'docs/src/dsge.md — #293 (T194 LOW sweep: Sims 2002 citation canonicalization, notation drift on the overview page)', 'docs/src/dsge_linear.md — #293 (T194: orphan Koop-Pesaran-Potter ref, notation)', 'docs/src/dsge_olg.md — #293 (T194: orphan Fujiwara-Teranishi reference on OLG)', 'docs/src/dsge_continuous.md — #293 (T194: `z` income-vs-endogenous notation drift)', "api_types.md/api_functions.md — #277 (T178) registers the CT/OLG TYPE docstrings (CTTwoAssetSolution, BlanchardOLG, etc.); this issue edits only the DSGE body pages' tables per the issue's own scoping note, so no same-region collision, but keep field lists consistent with T178", 'CLAUDE.md:244 — no other #276-331 issue edits this line (verified: T194/T195/T178 are docs/src only)'], 'effort': 'L', 'risk': 'med'}

=== VERIFY ===
{'issue': 289, 'verdict': 'CORRECTED', 'assessment': 'I independently read every cited file at the release/v0.6.6 tip. Six of the seven sub-defects are cleanly real and the proposed fixes are correct and complete against source: (1) Dynare count — dsge.md:14/:387 say "27-model" while the owning tier table dsge.md:398-406 sums to 24 and test/dynare_replication/ holds exactly 24 tier*.jl (+3 support = 27 .jl); CLAUDE.md:244 says "22 models" and :328 is the untouchable v0.5.0 historical note. (3) hub links — dsge.md never links dsge_ha/dsge_olg/dsge_continuous; anchors verified at line 1 of each child. (4) static recipes 3/6 carry reader-facing report() in ```julia blocks (anti-pattern no.12, docrule:381). (5a) dsge_olg.md has 0 admonitions, no BlanchardOLG keyword table, no blanchard_solve/blanchard_transition return tables, and a println at :117 — all proposed defaults/fields match blanchard.jl:64-65/99-106/256-282. (5b) dsge_continuous.md qualifies ct_hjb/ct_kfe though both are exported (MacroEconometricModels.jl:539), has only the ct_mit_shock keyword table, a 6-of-12-field CTTwoAssetSolution table (struct has 12 fields at two_asset.jl:87-100), and no Complete Example; kwargs verified at continuous_aiyagari.jl:266-270 and two_asset.jl:224-225. (6) dsge_ha.md:460-468 is a println loop (anti-pattern no.1). (7) dsge_hd.md:45-50 puts a @docs block AFTER References, violating docrule.md:60. BUT sub-defect (2) as specified is wrong: the research sourced the method list from the dispatch branch names (vfi_solver) and NOT from the docstring at gensys.jl:193, which explicitly states ":vfi -- Euler-equation time iteration (Coleman 1990), equivalent to :pfi (the name is historical, not value-function iteration)". So describing :vfi as "value function iteration" in the new hub table would be factually wrong, and the confident "seven->eight, the linear table OMITS :vfi (bug)" framing is itself questionable because :vfi is a historical alias of :pfi (7 distinct algorithms vs 8 accepted symbols). This is exactly the kind of stale audit source-read the verifier must catch, so the issue is real but the fix must be corrected.', 'corrections': 'SUB-DEFECT 2 (solve methods) — the only substantive correction:\n1. NEVER describe :vfi as "value function iteration". Source of truth src/dsge/gensys.jl:193 says :vfi is "Euler-equation time iteration (Coleman 1990), equivalent to :pfi (the name is historical, not value-function iteration)". Any hub/method table must describe :vfi as a historical alias of :pfi (Coleman 1990 time iteration), NOT VFI. Likewise :pfi per :192 is "Policy Function Iteration / Time Iteration (Coleman 1990)".\n2. The "seven -> eight" bump is debatable, not a clear bug. solve() accepts 8 method SYMBOLS but only 7 distinct ALGORITHMS because :vfi == :pfi. Therefore: (a) "seven solution methods" at dsge.md:3 is defensible as 7 distinct algorithms; (b) dsge_linear.md\'s 7-row table listing :pfi-but-not-:vfi is a reasonable presentation of the 7 distinct algorithms, not an omission bug. The implementer must pick ONE consistent story: either keep "seven distinct methods" everywhere, OR advertise "eight accepted method symbols" and explicitly flag :vfi as a historical alias of :pfi in the same table/sentence. Do not present :vfi as an 8th distinct algorithm. The genuinely valuable part of this sub-fix is orthogonal to the count: scope dsge_linear.md\'s :74-82 table to the 3 linear methods (:gensys/:blanchard_kahn/:klein) and add a cross-reference to the hub, since a page titled "Linear Solution Methods" carrying perturbation/projection/pfi/perfect_foresight rows is a scope smell (anti-pattern no.10). Keep dsge.md:3, the hub table, and CLAUDE.md:246 (the "PFI, or VFI" roadmap bullet) mutually consistent.\n3. Cross-check dsge_nonlinear.md (not in target_files) so the new hub 8/7-method table does not contradict its existing pfi/vfi description.\n\nMINOR:\n- The research\'s parenthetical docrule line refs for anti-patterns no.10 and no.12 drift: cite docrule.md:379 (no.10 Duplicated content) and :381 (no.12 static julia), plus :370 (no.1 println) and :60 (References last). The anti-pattern NUMBERS are correct; only the line numbers were off.\n- SUB-DEFECT 6: deleting the dsge_ha.md:460-468 loop outright drops the per-model beta values, which the table at :453-458 does NOT contain. Prefer converting the loop to a rendered NamedTuple/table (or add a beta column) rather than a blind delete, so the println dies without losing information.\nAll other proposed edits (Dynare 27->24 at dsge.md:14/:387; CLAUDE.md:244 22->24 with :328 untouched; three hub child links with verified anchors; OLG keyword+return tables/admonition/de-println; CT unqualify :60/:75, ct_steady_state/ct_two_asset_solve keyword tables, full 12-field CTTwoAssetSolution table, Complete Example; dsge_hd @docs move above References) are verified correct against source and should proceed as written.', 'collision_issues': [277, 293, 294], 'discriminating_power': 'n/a (docs-only issue; no test assertions involved)', 'final_effort': 'L'}