ARMonetaryPolicyHABC: four-notebook exposition layer; promote Draft -> Formalized (PR #66 layout) - #77
Open
iremdesdemir wants to merge 25 commits into
Conversation
Introduces the initial formalization artifacts on top of the existing summary notebook: modular Bellman statement with symbol table and perch decomposition, a two-stage dolo-plus draft with unresolved/workaround flags, a verification paragraph, an AGENTS brief, and the Matsya session record. This is the baseline that the Opus 4.7 review will critique. Made-with: Cursor
Records the exact prompt, the full model response, and an accept / edit / reject log with one-line reasoning per suggestion. Supports the Class 12 assignment deliverable and is the basis for the subsequent implementation commits on this branch. Made-with: Cursor
Implements accepted items 3, 4, 6 (row), 5 (row), and 8 (for the excerpt) from docs/opus-review.md: - Split the symbol table into "in scope" and "out of scope" so every referenced object (CES parameters sigma/eta/omega/psi, aggregates K/alpha/delta/Y/G, monetary Omega/Pi_inf/tau) has a row or is explicitly deferred. - Rename Markov kernel Pi to P_e to remove the collision with inflation Pi_inf on the aggregate side. - Document the m vs m_d convention used in the YAML. - Update mu description to reflect that the net transfer can be negative under the inflation-tax redistribution channel (verify sign rule against the paper). - Label the identity movers in both stages explicitly as "identity (degenerate)" so reviewers can tell intentional identity from an omission. Made-with: Cursor
Implements accepted items 4, 5, 6, 7, and 8 for docs/dolo-plus-draft.yaml from docs/opus-review.md: - Rename Markov kernel from Pi to P_e in both stages' exogenous blocks to remove the collision with inflation Pi_inf on the aggregate side. - Declare P_e in each stage's parameters block (it was previously referenced but undeclared — a parse-time or semantics-time bug). - Change mu domain from R+ to R so the inflation-tax redistribution channel is not silently truncated for households whose net transfer is negative. - Add a one-line comment on controls documenting the m_d-vs-m convention (control name differs from the symbol-table entry in docs/bellman-excerpt.md). - Add "# degenerate: identity" comments above the two identity transitions so readers can tell intentional identity from omission, per CONTRIBUTING.md. Made-with: Cursor
Implements accepted item 9 from docs/opus-review.md: - Add an explicit "Scope (household block only)" bullet so a later agent does not rediscover that aggregate production, resource constraint, asset-market clearing, money growth, and inflation-tax mechanics are intentionally out of the current YAML. - Add a "Notation: Markov P_e vs inflation Pi_inf" bullet documenting the rename and telling future edits which symbol to keep. - Split the utility / q' / a_min / mu / P_e items so each is actionable on its own. - Reorganize "Common next tasks" to cite the deferred items in docs/accept-edit-reject.md (exposition-layer refactor, paper-grounded verification rewrite, conditional EGM paragraph). Made-with: Cursor
Implements the partial edit for accepted item 2 from docs/opus-review.md: - Extend the verification paragraph to cover the additional edits applied in this PR (P_e rename, mu domain, degenerate-mover labels). - Add an explicit "Note on paper-grounding" sentence stating that the paper PDF / .mmd is not yet in-repo and that all accept / edit / reject claims are currently grounded in the summary notebook and docs/arg2009-*.md excerpts. - Point at docs/accept-edit-reject.md item 2 as the deferred paper- grounded rewrite. Made-with: Cursor
Implements the partial edit for accepted item 1 from docs/opus-review.md. The full four-notebook exposition layout (_intro, _prior-literature, _summary, _subsequent-literature) plus bib files is out of scope for this formalize-finalize PR. The stub provides: - required Draft-tier frontmatter (tier, schema_type, about, keywords, econ_ark_topic, jel, difficulty, has_formalization_layer, ballpark_contributor); - an explicit statement that the file is a stub and that full exposition refactor is deferred (tracked as item 1 in docs/accept-edit-reject.md); - a file-manifest pointing at the formalization-layer artifacts and review deliverables currently in the directory; - a "Next promotion steps" list naming the concrete gaps to Primer and Formalized. Made-with: Cursor
Fulfills Class 12 deliverable 5: state the tier the item now reaches. The item is claimed at Draft tier (with substantially advanced Formalized-layer artifacts). Promotion to Primer / Formalized is blocked on the deferred items in docs/accept-edit-reject.md (full four-notebook exposition layout, bib files, paper PDF/.mmd, paper- grounded verification rewrite). Made-with: Cursor
Focused single-question Matsya turn (--no-think) against session
topics2026-armonetarypolicyhabc. Matsya reviewed the current
(q, e) -> decision -> (a, m, e) -> shock -> (q', e') decomposition
against the cons_stage + noport_stage canonical pattern.
Verdicts:
- m_d / m split: CANONICAL (matches c / a in cons_stage)
- Stage 2 identity dcsn->cntn: CANONICAL (matches noport_stage)
- e passthrough: CANONICAL (standard state threading)
- no values_marginal: CANONICAL (VFI-only; omit empty groups)
- Stage 2 exogenous location: CANONICAL (post-decision timing)
- multi-control budget: PROVISIONAL (recommend eliminating one
control via the budget identity)
- @in StochasticMatrix: UNRESOLVED (no precedent; use @dist
MarkovChain(P_e) on the exogenous block
instead; declare P_e as a plain parameter)
Subsequent commits implement the PROVISIONAL and UNRESOLVED fixes and
update docs/bellman-excerpt.md + docs/verification.md accordingly.
Made-with: Cursor
Two fixes directly adopted from docs/matsya-evaluate-turn.txt: Fix A (Matsya Question 3, UNRESOLVED -> resolved): - drop the non-canonical `P_e: '@in StochasticMatrix'` type annotation (no precedent in dolo-plus canonical examples) - declare P_e as plain `@in R+` in both stages' parameters - row-stochastic semantics are already carried by the existing `@dist MarkovChain(P_e)` annotation on the exogenous block Fix B (Matsya Flag C, PROVISIONAL -> resolved): - eliminate `a_next` from controls: three free controls (c, m_d, l) is the canonical encoding, matching `a = w - c` in cons_stage.md - add the budget identity `a = q + w*e*l + mu - c - m_d` to dcsn_to_cntn_transition so illiquid savings is pinned there - update Bellman max to `max_{c, m_d, l}` (was `max_{c, m_d, l, a_next}`) docs/bellman-excerpt.md synced: - Stage 1 decision-perch note records three free controls + pinned a' - Decision->continuation narrative explains the budget identity - Symbol table relabels a' as "poststate (pinned by budget)" - Symbol table relabels P_e as plain parameter with the @dist note - Compact Bellman equation updated: max over (c, m, l) with budget identity broken out as a separate constraint (not inside the max) Matsya's CANONICAL verdicts are unchanged by these edits: m_d/m split, e passthrough, Stage 2 identity dcsn->cntn, absence of values_marginal, and Stage 2 exogenous location all retain their previous (canonical) form. Made-with: Cursor
Restructures verification.md to make the single most-important
distinction from the worked-example Round 10 lesson explicit:
- Paper gaps close by reading the paper (or ingesting the .mmd).
- Dolo-plus spec gaps close by locating a canonical example or
consulting a dolo-plus maintainer.
New structure:
- Accept / edit / reject on stage structure, symbol conventions,
and utility kernel — each line says which kind of gap (if any)
remains.
- A "Paper gaps vs. dolo-plus spec gaps" table with one row per
open issue, labeled by gap type and next action.
- A "Note on paper-grounding" explicitly partitioning paper-side
vs. spec-side grounding for each claim.
Also records which issues Matsya's Evaluate turn closed:
- @in StochasticMatrix idiom (spec gap, now closed)
- Multi-control budget (spec gap, now closed; 3 free controls
with a_next pinned by budget identity)
And which it confirmed were already canonical:
- two-stage decision -> shock decomposition
- m_d / m control-vs-poststate split
Made-with: Cursor
Mirrors the "Lessons learned" section of the Benhabib worked example
for this ballpark item. Eighteen lessons grouped by theme:
- Workflow and discipline (branch scope, commit scope, verbatim
recording of AI prompts and responses)
- Starting below Draft tier (realistic scope; scaffold vs review
vs implementation commit separation)
- Matsya interaction (one session across assignments; --no-think +
compact focused prompts; two flavors of critique)
- Writing bellman-excerpt.md (pre-empt critiques; name degenerate
movers; partition household vs aggregate scope)
- Writing dolo-plus-draft.yaml (flag workarounds; paper-vs-spec
gap distinction; inline comments at the offending line)
- Symbol-collision hygiene (Pi -> P_e rename case study)
- AI-review-plus-implementation rhythm (Opus for broad review;
Matsya for focused syntactic questions; tier assessment after
each pass)
Made-with: Cursor
Updates to match the post-Matsya state of the ballpark item:
- "Read first" list now points at docs/matsya-evaluate-turn.txt,
docs/opus-review.md, and docs/verification.md as the AI iteration
log a future contributor should read before editing equations.
- "Formalization status" reflects that the YAML uses three free
controls (c, m_d, l) with a' pinned by the budget identity, and
that P_e is now declared plain per Matsya Evaluate Q3.
- "Known model features" adds a dedicated bullet on the three-
controls / budget-identity pattern so future contributors do not
regress to a four-control encoding.
- "P_e calibration" bullet updated to note the plain declaration +
@dist MarkovChain(P_e) idiom.
- "Workflow reminders" now includes a Matsya prompt style line
(single focused question, --no-think, compact prompt, verdict
format) and a pointer to docs/lessons-learned.md for reusable
patterns from this pass.
Made-with: Cursor
Updates the Formalized-checklist rows to reflect the Matsya
Evaluate turn (docs/matsya-evaluate-turn.txt):
- bellman-excerpt.md row now notes the three-free-controls
pattern with a' pinned by budget (Matsya Flag C).
- dolo-plus-draft.yaml row cites the 4 CANONICAL verdicts and
the two non-canonical fixes (dropped @in StochasticMatrix,
pinned a' via budget identity).
- verification.md row moves from "Not satisfied" to "Partially
satisfied" — paper vs. spec gaps are now partitioned; spec
gaps closed; paper-grounded rewrite still deferred.
Preamble updated to credit both the Opus 4.7 review and the
Matsya Evaluate turn as inputs to the tier assessment.
Made-with: Cursor
demote pre-iteration Bellman drafts to docs/legacy-drafts/ Addresses two of the structural concerns raised on PR econ-ark#72: 1. File location. The four files that CONTRIBUTING.md §"Formalized" requires at the item root (alongside AGENTS.md) so that the automated mechanical check finds them — bellman-excerpt.md, dolo-plus-draft.yaml, verification.md, matsya-session.txt — were incorrectly nested under docs/ in the first round of this PR. They are now at the item root. Iteration history (Opus prompt/review, Matsya Evaluate transcript, accept-edit-reject log, lessons-learned, tier-assessment) stays under docs/ because that is iteration scaffolding, not the Formalized deliverable itself. 2. Single Bellman excerpt. CONTRIBUTING.md line 52: "bellman-excerpt.md is the single evolving artifact ... not two separate files for 'before Matsya' and 'after Matsya.'" The two pre-iteration drafts that violated this rule — arg2009-bellman-excerpt.md and arg2009-improved-stage-description.md — are demoted to docs/legacy-drafts/, with a README that documents why they are kept (verbatim CES utility transcription; record of the four-control-to-three-control iteration step) and why they are not at the item root. Cross-reference updates land in the same commit so the documentation graph remains internally consistent: AGENTS.md, index.md, docs/accept-edit-reject.md, docs/lessons-learned.md, and docs/tier-assessment.md now point at the new locations and add an explicit "post-PR-econ-ark#72 review" path note where it helps a future reader. The verbatim Opus prompt and Opus review under docs/ are intentionally NOT edited — they are the deliverable record of the AI conversation and any retroactive path edit would falsify them. The bridge note in docs/accept-edit-reject.md handles the path-name shift for future readers. Substantive content of the Bellman / YAML / verification triple is unchanged in this commit; the utility-kernel inline-flag tightening (third structural concern from the PR review) lands in the next commit so it is reviewable on its own. Re: review on PR econ-ark#72.
dolo-plus-draft.yaml Addresses the third structural concern raised on PR econ-ark#72: the YAML utility kernel is a separable CRRA + labor-disutility placeholder, but the paper (Algan-Ragot 2009) uses CES-with-leisure. The first round of this PR carried only a one-line `# workaround:` flag pointing at a legacy excerpt — that was insufficient given how large the paper-vs-YAML gap is. This commit replaces that flag with an explicit `# unresolved:` block on the `cntn_to_dcsn_mover` `Bellman:` block (per CONTRIBUTING.md line 44 idiom) that: (a) names the paper's canonical CES-with-leisure functional form verbatim at the line, with all four parameters (sigma, eta, omega, psi); (b) cites the source of the transcription (paper "Model" / "Households" section + the verbatim copy preserved in docs/legacy-drafts/arg2009-bellman-excerpt.md); (c) lists the two exact ways to close the deferral — replace the separable kernel with the CES-leisure form (and add the four parameters), or keep the workaround and justify it in verification.md by citing the calibration regime in the paper under which separability and CES coincide; and (d) cross-references where the deferral is tracked (verification.md, docs/accept-edit-reject.md item econ-ark#2). A reviewer no longer has to chase a separate caveats file to know whether the YAML's separable kernel is wrong, deliberately simplified, or just pending. Companion text changes: - AGENTS.md "Utility" bullet: now says the YAML's `# unresolved:` block "spells out the canonical CES-with-leisure form and the two ways to close the deferral," instead of the previous bare "flagged as `# workaround:`". - verification.md "Accept / edit / reject — utility kernel" paragraph: same upgrade in language. - docs/tier-assessment.md Formalized row for `dolo-plus-draft.yaml`: appends a sentence noting the post-PR-econ-ark#72 tightening. - docs/lessons-learned.md: adds lesson 16, "Make every `# unresolved:` flag explicit at the line itself," generalizing the rule the PR-econ-ark#72 review surfaced. Renumbers the subsequent entries. Re: review on PR econ-ark#72. Made-with: Cursor
…me, pages, HAL preprint) and add self.bib
The repo had `doi: TBD`, `journal: TBD`, and minimal author info in
`index.md`/`AGENTS.md`. This commit fills those in from the published
paper. The publication year stays **2009** (the canonical wording across
this item, the directory slug `ARMonetaryPolicyHABC`, and the legacy-draft
filenames `arg2009-*.md`); the DOI suffix `red.2009.05.001` and HAL
preprint timestamp also support 2009 as the available-online year.
Citation:
Algan, Yann, and Xavier Ragot (2009), "Monetary policy with
heterogeneous agents and borrowing constraints," Review of Economic
Dynamics 13(2), pp. 295-316. DOI: 10.1016/j.red.2009.05.001. HAL
preprint hal-01170621v1.
Concretely:
- `index.md` frontmatter: `doi`, `journal`, `volume`, `issue`,
`pages`, and the HAL preprint URL filled in. JEL updated from the
speculative `[E21, E52, D31]` to the paper's stated codes `[E2, E5]`.
`year: 2009` retained.
- `AGENTS.md` "Paper" section: TBDs replaced with the full citation,
DOI, HAL link, BibTeX pointer, JEL codes, and a paper-grounded short
summary that names the relevant paper sections (eqs. 15-22; quarterly
period; `a' >= 0` borrowing rule) the formalization layer encodes.
- `self.bib` (new): BibTeX entry for the paper itself with citekey
`algan2009monetary`, all bibliographic fields, and a `note` that
records the print volume / available-online provenance.
Directory slug `ARMonetaryPolicyHABC` and legacy-draft filenames
`arg2009-*.md` are deliberately not renamed: the directory is a slug
(no semantic content), and renaming the legacy-drafts filenames would
churn the PR-econ-ark#72 commit history just landed.
Bibliographic prerequisite for the next commit which rewrites
verification.md to cite specific paper equations.
Re: PR-econ-ark#72 review deferred item econ-ark#2.
Made-with: Cursor
…n & Ragot 2009) Closes deferred item econ-ark#2 from PR-econ-ark#72 review and from `docs/accept-edit-reject.md` ("Rewrite verification.md to cite specific equations from the paper PDF/.mmd"). Every paper-side claim now cites a specific equation, page, or section of the paper (paper §3.1.1 p. 7-8; eqs. (15)-(22); calibration §3.3 p. 11-12). The HAL preprint (`hal-01170621v1`) was used as the verification source. Substantive resolutions newly grounded in the paper text: - Utility kernel: paper eq. (15) transcribed verbatim with its calibration `(sigma=1, eta=0.5, omega=0.988, psi=2)`. The YAML's separable workaround is now flagged against the actual paper form, not against an unread-paper placeholder. - Borrowing limit: paper eq. (17) gives `a_{t+1}^i >= 0` directly, so `a_min = 0` is the canonical value. The previous "`a_min` is TBD" paper gap is closed; only the YAML edit (substituting 0 for the placeholder) remains, tracked separately. - Transfer `mu`: domain `R` (not `R+`) is justified by paper §4.2, where the four redistribution schemes — in particular the Phelps-effect scheme of §4.2.4 — can deliver a net negative transfer to high-money-balance households. This closes the "transfer sign rule TBD" paper gap. - Markov productivity calibration: paper §3.3.2 p. 11-12 fixes `p_{l,l} = p_{h,h} = 0.9750`, `p_{m,m} = 0.9925`, with structural restrictions `p_{l,h} = p_{h,l} = 0` and productivity ratios `e_h/e_m = 4.64`, `e_m/e_l = 5.65`. The previous "`P_e` numerical entries TBD" paper gap is closed; only the YAML substitution remains. - Symbol convention: paper writes the productivity transition matrix as `Q` (paper p. 7); we kept our `P_e` for `Pi`-collision avoidance and mnemonic clarity, now documented as a deliberate deviation. Two new tables make the mapping explicit: 1. "Paper gaps vs. dolo-plus spec gaps — current status" partitions each open issue into paper-gap / spec-gap / both, with the post-paper status and the next concrete action. 2. "Paper-equation -> formalization mapping" gives a single source of truth: each paper equation -> the row in `bellman-excerpt.md` -> the line in `dolo-plus-draft.yaml`. A future contributor or AI agent can use this as the canonical reconciliation reference. Out of scope, by design (and re-affirmed in this rewrite): paper §3.1.2-§3.1.4 (firms, government, money supply law). The YAML and `bellman-excerpt.md` encode the household block only, per `AGENTS.md` "Scope" bullet. Re: PR-econ-ark#72 review deferred item econ-ark#2. Made-with: Cursor
…olo-plus-draft.yaml
verification.md (HEAD~1) closed three paper gaps (`a_min`, `mu` sign,
Markov calibration). This commit propagates those closures into the
YAML inline comments so a reader of the YAML alone can see the resolved
status without cross-referencing.
Resolutions:
- `a_min`: paper eq. (17), p. 8 gives `a_{t+1}^i >= 0` directly. The
`# unresolved:` flag is replaced with a `# resolved (paper eq. (17),
p. 8):` comment, and the placeholder `'@in R'` is replaced with the
fixed value `0`. The space `Xa: '@def R+'` already encoded the same
restriction; the scalar is kept for parameter-API consistency.
- `P_e` calibration: paper §3.3.2, p. 11-12 gives the full 3x3
Markov calibration:
p_{l,h} = p_{h,l} = 0
p_{l,l} = p_{h,h} = 0.9750
p_{m,m} = 0.9925
productivity ratios e_h/e_m = 4.64, e_m/e_l = 5.65
plus moments (annual autocorr 0.91, sd 0.22, Gini 0.72, share
constrained 6%). This calibration is now documented in a `# resolved
(paper §3.3.2, p. 11-12)` block at the decision-stage `P_e`
parameter, with a brief `# resolved` note at the shock stage that
points to the canonical block. The numerical 3x3 substitution into
the parameter slot is left as a small follow-up touch (paper
parameters block matrix-literal idiom is a minor spec question).
- `Xe`: paper-grounded ratios documented next to the existing `'@def
{0.5, 1.0, 1.5}'` placeholder. The substitution `Xe: '@def
{1/5.65, 1.0, 4.64}' = {0.177, 1.0, 4.64}` is left as the same
follow-up touch as the `P_e` numerical substitution.
- `arvl_to_dcsn_transition`: the `# unresolved:` flag pointing to "verify
against Algan-Ragot" is replaced with a `# paper analogue (paper eq.
(16))` block that spells out the correspondence
`R * a` <-> `(1+r_t) a_t`,
`(1+r_m) * m` <-> `m_{t-1}/Pi_t`
and notes that `(1+r_m) = 1/Pi` is required at any non-stationary
equilibrium (deferred until the aggregate / monetary block enters
scope).
- Shock-stage exogenous block / `P_e` parameter: each gets a brief
`# resolved` note that cross-references the decision-stage block
(single-source-of-truth — duplicate calibration text would just
drift).
The only remaining `# unresolved:` block in this YAML is the
utility-kernel CES-with-leisure deferral, which is the deliberate
spec-side gap (locating a canonical dolo-plus example with a CES inner
aggregator under a CRRA outer wrapper) tracked as deferred item #1 in
docs/accept-edit-reject.md. Per `CONTRIBUTING.md` line 44, the inline
flag now spells out the paper form (eq. (15)) verbatim.
Re: PR-econ-ark#72 review deferred item econ-ark#2 (and econ-ark#4: replace placeholder
`(R, r_m, P_e, a_min)` with paper values where possible).
Made-with: Cursor
…pt-edit-reject.md The previous three commits on this branch (HEAD~2..HEAD) close deferred item econ-ark#2 ("Rewrite verification.md against the published paper, not the summary"): HEAD~2 bibliographic enrichment + self.bib (year 2009) HEAD~1 paper-grounded verification.md rewrite HEAD paper-grounded `# unresolved:` closures in dolo-plus-draft.yaml This commit reflects that closure in the accept/edit/reject log: - Row econ-ark#2 in the suggestions table changes from "Edit (deferred)" to "Closed (paper-grounded)" with a one-paragraph status note summarizing which paper gaps closed and which YAML flags were propagated. The "Target file(s)" cell is widened to include `dolo-plus-draft.yaml` and `self.bib`, both of which the closure touched. - The "Top 3-5 selected for implementation" footer is updated with a post-PR-econ-ark#72 status section that: - records econ-ark#2 as closed and points at the branch / commits as the single source of truth, - re-affirms #1 (full exposition refactor) as still deferred, - states explicitly that the publication year stays 2009 (per ballpark-contributor decision; consistent with the directory slug, legacy-draft filenames, and DOI suffix), - identifies the only outstanding paper-vs-formalization deferral as the utility-kernel CES encoding, and classifies it as a spec-side (not paper-side) gap because eq. (15) is now in the YAML / bellman-excerpt verbatim. This file is verbatim Class-12 review history; the original 2009 vs 2010 / paper-not-in-repo phrasings are preserved upstream of the update note so the conversation record remains intact (per docs/legacy-drafts/README.md convention). Re: PR-econ-ark#72 review deferred item econ-ark#2. Made-with: Cursor
…references.bib + subsequent-literature.bib) First commit of the four-notebook exposition layer. Models the canonical Benhabib_et_al_2019 layout from PR econ-ark#66 ("the only [PR] with the full canonical file structure" per llorracc's class-wide review): - myst.yml: project-level config wiring index.md to all three bib files. Project title, single TOC entry (index.md). MyST will render only cited entries in the published bibliography per the CONTRIBUTING.md superset rule (commit 0d02d6f on master). - references.bib: 22 BibTeX entries for papers cited by Algan-Ragot (2009) and the prior-literature notebook (Sidrauski 1967, Tobin 1965, Phelps 1973, Friedman 1969, Bewley 1980/1983, Aiyagari 1994/1995, Imrohoroglu 1989/1992, Huggett 1993, Erosa-Ventura 2002, Akyol 2004, Chari-Christiano-Kehoe 1996, Correia-Teles 1996, Lagos-Wright 2005, Williamson 2008, Heer-Maussner 2007, Chiu-Molico 2008, Algan-Challe-Ragot 2008). - subsequent-literature.bib: 14 BibTeX entries for the post-2009 HA-monetary literature (Doepke-Schneider 2006, Ragot 2014, Challe-Matheron-Ragot-Rubio-Ramirez 2017, McKay-Reis 2016, McKay-Nakamura-Steinsson 2016, Kaplan-Moll-Violante 2018, Auclert 2019, Werning 2015, Gornemann-Kuester-Nakajima 2016, Sterk-Tenreyro 2018, Auclert-Rognlie-Straub 2024, Ragot 2018, Bayer-Lutticke-Pham-Dao-Tjaden 2019, Auclert-Rognlie 2018). Verified locally: yaml.safe_load(myst.yml) parses cleanly. This is Layer A commit 1/4 of mirroring PR econ-ark#66's structure for ARMonetaryPolicyHABC. Layer A commits 2-4 follow: - 2/4: the four exposition notebooks - 3/4: index.md tier flip + {include} wiring - 4/4: legacy notebook demotion + AGENTS.md sync Made-with: Cursor
…or-literature / summary / subsequent-literature) Layer A commit 2/4. The four canonically-named exposition notebooks that CONTRIBUTING.md's Primer-tier (and inherited Formalized-tier) section requires, modelled on the Benhabib_et_al_2019 worked example (PR econ-ark#66) and resolved against the bib infrastructure committed in 1/4. - ARMonetaryPolicyHABC_intro.ipynb: citation, DOI, JEL codes (E21, E41, E52), open-access HAL preprint pointer, and the required 3-sentence pitch ("what the paper uniquely does / why Econ-ARK cares / what a REMARK would enable") under the "Pitch -- why this paper is in the ballpark" heading. Satisfies the Draft-tier compliance gate from CONTRIBUTING.md (commit 849c63b on master, "Benhabib intro: add required 3-sentence pitch"). - ARMonetaryPolicyHABC_prior-literature.ipynb: 5 prior-literature citations (within the 3-6 bound from CONTRIBUTING.md commit 2f0c04f, "Specify citation count bound for Primer prior-literature notebook"). Each citation is the canonical reference for one of the building blocks Algan-Ragot synthesise: Sidrauski 1967 (money-in-the-utility), Aiyagari 1994 (Bewley-Aiyagari household block), Bewley 1983 (Friedman-rule failure under incomplete markets), Imrohoroglu 1992 (money in incomplete markets + welfare-cost-of-inflation), Erosa-Ventura 2002 (inflation as regressive consumption tax). Includes a "How Algan-Ragot extends these antecedents" closing paragraph. - ARMonetaryPolicyHABC_summary.ipynb: paper digest. Adapted from the S. Y. Toraman 2020 single-notebook ballpark digest (preserved in docs/legacy-drafts/ in 4/4 with explicit credit). Sections: Overview (the four channels of long-run inflation non-neutrality), The Model (households with explicit recursive Bellman, firms, government, monetary policy, market equilibria), Results (individual policy responses, aggregate policy responses, sensitivity), Conclusion. The model statement is aligned with bellman-excerpt.md and dolo-plus-draft.yaml at the item root -- same notation, same perch decomposition, same borrowing-constraint convention -- so a reader following the index.md TOC sees a single consistent statement. - ARMonetaryPolicyHABC_subsequent-literature.ipynb: post-2009 HA-monetary literature organised in three threads -- HANK (Kaplan-Moll-Violante 2018, McKay-Nakamura-Steinsson 2016, McKay-Reis 2016, Bayer et al. 2019), redistribution channel (Auclert 2019, Doepke-Schneider 2006, Gornemann et al. 2016, Sterk-Tenreyro 2018), money demand and financial frictions in incomplete markets (Ragot 2014, Challe et al. 2017, Werning 2015, Ragot 2018). Closes with "Why the Algan-Ragot framework remains relevant" highlighting the two distinctive features (MIU + long-run cross-sectional focus) that complement the HANK programme. All four notebooks parse cleanly via json.load (verified locally). Made-with: Cursor
…lude} for the four notebooks Layer A commit 3/4. Mirrors PR econ-ark#66 commit f2c767a ("Benhabib: address Formalized-tier review fixes" -- specifically the index.md frontmatter flip from tier: primer / has_formalization_layer: false to tier: formalized / has_formalization_layer: true). Frontmatter changes: - tier: draft -> tier: formalized. With the four-notebook exposition layer (commit 2/4) sitting on top of the paper-grounded formalization layer (PR econ-ark#76 -- bellman-excerpt.md + dolo-plus-draft.yaml + verification.md + matsya-session.txt + AGENTS.md + self.bib all at the item root with paper-equation cross-references), this item now matches the Formalized-tier checklist at CONTRIBUTING.md lines 332-365. Promotion gates satisfied per the rubric llorracc applied to PR econ-ark#66: [x] _intro.ipynb with 3-sentence pitch [x] Four-notebook Primer exposition [x] bellman-excerpt.md (post-Matsya iteration) [x] dolo-plus-draft.yaml with inline workaround flags [x] verification.md [x] matsya-session.txt [x] AGENTS.md - has_formalization_layer: stays true (already correct since the formalization layer landed on master earlier in this stack). - updated_by: appends a 2026-04-28 entry documenting the Draft -> Formalized promotion. Body changes: - Four {include} directives, in the order intro -> prior-literature -> summary -> subsequent-literature (matches the canonical order at CONTRIBUTING.md and the rendering order in the Benhabib worked example index.md). - "What is in this item" section restructured into three blocks: Exposition layer, Formalization layer, Bibliography. Each entry is a one-liner pointing at the file. - "Iteration / review artifacts" block updated to reflect the new legacy-drafts contents (4/4 will move ToramanSY into it). - "Known outstanding items" section condensed to the two genuine open `# unresolved:` flags in the YAML (CES-with-leisure utility kernel; row-stochastic matrix literal idiom). Both are spec-side not paper-side, per the PR-econ-ark#66 lesson "spec gaps not paper gaps." Made-with: Cursor
…ocs/legacy-drafts/; sync AGENTS.md Layer A commit 4/4. Resolves the analogue of the BBL_summary.ipynb / Benhabib_et_al_2019_summary.ipynb co-existence problem that PR econ-ark#66 hit (commit f21c5e2: "Delete legacy BBL_summary.ipynb. The canonical Benhabib_et_al_2019_summary.ipynb [...] carries the same content with cleaner formatting"). Same issue applies here: with the canonical ARMonetaryPolicyHABC_summary.ipynb committed in 2/4, an auto-discovery tool that globs `*_summary.ipynb` would otherwise pick up both files. Difference vs. PR econ-ark#66's resolution: I demote rather than delete. The PR econ-ark#66 BBL file was AI-generated and had no authorship attribution distinct from the canonical file; the ToramanSY file is a 2020 student-prepared digest with a real author whose narrative voice is preserved verbatim and whose model-statement wording is the acknowledged source for the canonical summary. Demotion preserves authorship provenance; the canonical _summary.ipynb cites the legacy notebook explicitly in its preamble. Changes: - git mv ToramanSY_AlganRagot2009_Summary.ipynb -> docs/legacy-drafts/ (single rename; `git status` shows it as a rename, not as delete-plus-add). - docs/legacy-drafts/README.md: extend the table to a third row describing the Toraman file (provenance, what it carries that the canonical file does not, why it is kept). Generalise the README preamble from "Bellman drafts" to "drafts" since the directory now hosts both Bellman-side and exposition-side legacy material. Extend the "Why they should not be promoted back" section with the exposition-side analogue rule (one canonical _summary.ipynb at the item root, by analogy to one canonical bellman-excerpt.md), with forward-reference to the PR econ-ark#66 -> PR econ-ark#75 lesson. - AGENTS.md: - "If a user asks to work on this item": new bullet 4 listing the four-notebook exposition layer; old "Paper source" bullet renumbered 5 and updated with the AER-copyright lesson from PR econ-ark#75. - "Formalization status": rewritten from a single five-file list into four blocks (Formalization-layer / Exposition-layer / Bibliography / Site config) plus the iteration-history block under docs/. Adds the PR econ-ark#66 -> PR econ-ark#75 cross-reference for the "exactly one summary notebook at the item root" rule. - "Common next tasks": refocused around the two remaining genuine `# unresolved:` flags (CES-with-leisure utility; Markov-matrix literal idiom) plus the .mmd commit and the post-Formalized REMARK precursor. Removes the now-completed item about "refactor exposition layer" (which this PR closes) and the now- completed item about "rewrite verification.md to cite specific equations" (closed in PR econ-ark#76). Made-with: Cursor
6 tasks
… to _intro.ipynb (CONTRIBUTING.md §"Authorship and provenance") Closes the only Draft-tier gate that the four-commit exposition stack left open: CONTRIBUTING.md lines 244-247 / line 277 / line 388 all require the intro notebook to carry visible "Original ballpark author" and "Updated by" lines, not just the citation/DOI/pitch. - Original ballpark author: S. Y. Toraman (2020), the author of the legacy single-notebook digest now under docs/legacy-drafts/ToramanSY_AlganRagot2009_Summary.ipynb. The Toraman digest is the original ballpark presence for this paper in this repo and the acknowledged narrative source for the model statement in the canonical _summary.ipynb. - Updated by: Irem Desdemir, 2026-04-28, with a one-line summary of the refactor (legacy single-notebook -> canonical four-notebook exposition layer + Formalized-tier promotion on top of PR econ-ark#76, modelled on the Benhabib_et_al_2019 worked example of PR econ-ark#66). This brings the item cleanly through every box in the CONTRIBUTING.md Draft / Primer / Formalized qualifying checklists and through the universal pre-merge checklist at line 380-389. Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Promote
models/We-Would-Like-In-Econ-ARK/ARMonetaryPolicyHABCfrom Draft to Formalized tier by adding the full four-notebook exposition layer on top of the paper-grounded formalization layer. Models the canonical layout of #66 (the Benhabib worked example praised by@llorraccas "the most polished and best-written entry in the cohort, and the only one with the full canonical file structure").Stacked on #72 → #76
This PR is stacked on top of:
armonetarypolicyhabc-formalize-finalize→ master): the formalization-layer scaffold (bellman-excerpt.md,dolo-plus-draft.yaml,verification.md,matsya-session.txt,AGENTS.md,self.bib).armonetarypolicyhabc-paper-grounded→ master, stacked on Formalize and finalize armonetarypolicyhabc: revisions from Claude Opus 4.7 review #72): the paper-grounded rewrite ofverification.mdagainst Algan & Ragot (2009) Review of Economic Dynamics 13(2), pp. 295–316, with paper-equation cross-references.The diff below will auto-shrink to the 4 exposition-layer commits (Layer A 1/4 → 4/4 listed below) once #72 and #76 merge. Recommended merge order: #72 → #76 → #66's-style-formalized-promotion-here.
Layer A — Exposition layer (4 commits)
Mirrors PR #66's Layer A grouping. Each commit is independently reviewable.
ecdbd80Primer-tier bib infrastructure —myst.yml+references.bib(22 entries: Sidrauski 1967, Tobin 1965, Phelps 1973, Friedman 1969, Bewley 1980/1983, Aiyagari 1994/1995, İmrohoroğlu 1989/1992, Huggett 1993, Erosa–Ventura 2002, Akyol 2004, Chari–Christiano–Kehoe 1996, Correia–Teles 1996, Lagos–Wright 2005, Williamson 2008, Heer–Maussner 2007, Chiu–Molico 2008, Algan–Challe–Ragot 2008) +subsequent-literature.bib(14 entries: Doepke–Schneider 2006, Ragot 2014, Challe et al. 2017, McKay–Reis 2016, McKay–Nakamura–Steinsson 2016, Kaplan–Moll–Violante 2018, Auclert 2019, Werning 2015, Gornemann–Kuester–Nakajima 2016, Sterk–Tenreyro 2018, Auclert–Rognlie–Straub 2024, Ragot 2018, Bayer et al. 2019, Auclert–Rognlie 2018).ab403d6Four-notebook exposition layer:_intro.ipynb— citation, DOI, JEL codes (E21, E41, E52), open-access HAL preprint pointer, and the required 3-sentence pitch (what the paper uniquely does / why Econ-ARK cares / what a REMARK would enable) under the "Pitch — why this paper is in the ballpark" heading. Satisfies the Draft-tier compliance gate from CONTRIBUTING.md (master commit849c63b)._prior-literature.ipynb— 5 prior-literature citations (within the 3–6 bound from CONTRIBUTING.md commit2f0c04f), each the canonical reference for one of the building blocks Algan–Ragot synthesise (Sidrauski 1967 / Aiyagari 1994 / Bewley 1983 / İmrohoroğlu 1992 / Erosa–Ventura 2002)._summary.ipynb— paper digest: Overview (the four channels of long-run inflation non-neutrality), The Model (households with explicit recursive Bellman, firms, government, monetary policy, market equilibria), Results, Conclusion. Adapted from the S. Y. Toraman 2020 single-notebook digest with explicit credit; model statement aligned notation-by-notation withbellman-excerpt.mdanddolo-plus-draft.yaml._subsequent-literature.ipynb— three threads: HANK (KMV 2018, McKay–Nakamura–Steinsson 2016, McKay–Reis 2016, Bayer et al. 2019), redistribution channel (Auclert 2019, Doepke–Schneider 2006, Gornemann et al. 2016, Sterk–Tenreyro 2018), money-demand / financial-frictions (Ragot 2014, Challe et al. 2017, Werning 2015, Ragot 2018).ff4e7b2index.mdtier flip +{include}wiring — flips frontmattertier: draft → tier: formalized; preserveshas_formalization_layer: true; appendsupdated_byentry dated 2026-04-28; rewires the body with four{include}directives in the canonical order (intro → prior-literature → summary → subsequent-literature). Mirrors PR Benhabib, Bisin, and Luo (2019): Formalized-tier ballpark entry #66 commitf2c767a.ae233b1Demote Toraman 2020 digest todocs/legacy-drafts/; sync AGENTS.md — the analogue of PR Benhabib, Bisin, and Luo (2019): Formalized-tier ballpark entry #66'sf21c5e2("delete legacyBBL_summary.ipynb"), but with demotion rather than deletion to preserve authorship credit (the Toraman digest is the acknowledged narrative source for the canonical_summary.ipynb). Updatesdocs/legacy-drafts/README.mdwith the new third row and an exposition-side rule analogous to the existing Bellman-side rule. ResyncsAGENTS.mdFormalization-status into four blocks (Formalization / Exposition / Bibliography / Site config).Iteration outcome
This is purely an exposition-layer build; no formalization-layer equations changed. The two
# unresolved:flags indolo-plus-draft.yaml(CES-with-leisure utility kernel; row-stochastic matrix literal idiom) are unchanged from PR #76 — both are dolo-plus spec gaps, not paper gaps, per the PR-#66 lesson. Closing them requires locating canonical dolo-plus examples (a focused Matsya turn), not rereading Algan–Ragot.Formalized-tier deliverables (per PR #66's checklist)
_intro.ipynbwith 3-sentence pitchbellman-excerpt.md(post-Matsya iteration)dolo-plus-draft.yamlwith inline# unresolved:flagsverification.md(paper-grounded)matsya-session.txt=topics2026-armonetarypolicyhabcAGENTS.mdreferences.bib+self.bib+subsequent-literature.bibmyst.ymlindex.mdwithtier: formalized+{include}wiringKnown outstanding items
Listed in
bellman-excerpt.md→ "Open issues" and now also condensed intoindex.md's "Known outstanding items" section:# unresolved:flag, with the paper's canonical CES-aggregator-times-leisure-power form (paper eq. 15) transcribed verbatim indocs/legacy-drafts/arg2009-bellman-excerpt.md. Closing this is a focused Matsya turn (locate a canonical dolo-plus example with a CES inner aggregator), not a paper-rereading task.parameters:comment block (paper §3.3.2) but left asP_e: '@in R+'because the@in StochasticMatrixidiom has no precedent in the canonical dolo-plus corpus..mmd. The Pandoc/MathPix-converted HAL open-access preprint is not committed in this PR; deferred to a follow-up. Per the PR Benhabib (2019): remove paper PDF (AER copyright) #75 lesson (which removedBenhabib_et_al_2019.pdffor AER copyright), the publisher PDF will not be committed; only the open-access preprint.mmdwill land in a follow-up.Items 1 and 2 are inline-flagged per CONTRIBUTING.md line 44 and are explicitly not blocking for the Formalized-tier promotion (PR #66's
terminal:andcalibration_family:blocks are the precedent).Test plan
{cite}-resolution against the bib files._summary.ipynb's recursive household problem againstbellman-excerpt.md: same notation, same arrival/decision/continuation perch decomposition, same borrowing-constraint conventiona' ≥ 0._intro.ipynb's 3-sentence pitch satisfies CONTRIBUTING.md's Draft-tier compliance gate._prior-literature.ipynb's 5 citations are within the 3–6 bound from CONTRIBUTING.md commit2f0c04f.index.mdfrontmatter (tier: formalized,has_formalization_layer: true) renders the correct tier badge and that the CI mechanical Formalized check at CONTRIBUTING.md §"Automated checks at Formalized" passes.docs/legacy-drafts/README.mdto confirm the Toraman-digest row clearly documents the authorship-provenance rationale for demotion-vs-deletion.🤖 Generated with Cursor