Make the Readiness Engine profile-driven + city-facing app PRD#4
Open
MartinWainstein wants to merge 14 commits into
Open
Make the Readiness Engine profile-driven + city-facing app PRD#4MartinWainstein wants to merge 14 commits into
MartinWainstein wants to merge 14 commits into
Conversation
Extract IDB SFP's hardcoded eligibility logic into a pluggable 'readiness profile' (readiness-profiles.js). scoring.js now derives weights, tiers, the project-eligibility gate and the documentary checklist from the active profile; the default 'idb-sfp' profile reproduces prior behavior byte-for-byte (verified: 567 assertions across 63 SNGs, 0 diffs). Other MDBs (CAF, World Bank, EIB, GCF) plug in their own profile. This makes readiness the bridge between the City-Funder Matching Engine and any funder's pipeline. Co-Authored-By: Claude Opus 4.8 <[email protected]>
City-facing app spec for autonomous build: the 7-step journey (discover -> pick target -> diagnose readiness -> prepare -> pool -> submit), grounded in a primary-source review of CityCatalyst's Journey Navigator module model, OAuth 2.0 / PKCE, HIAP prioritizer, and Global Data API. Joins the City-Funder Matching Engine and the IDB Control Tower via the readiness-profile contract. Co-Authored-By: Claude Opus 4.8 <[email protected]>
The city-facing front door that joins the two modules: a CityCatalyst-styled Next.js app implementing the 7-step journey (enter -> discover -> pick target -> diagnose readiness -> prepare -> pool -> submit). When a city presses Ready, the deal posts to /api/submissions and appears in the funder-pipeline view (stands in for the IDB Control Tower). - Readiness scored by the vendored profile-driven engine (control-tower). - Real data: four-pillar readiness for 6 Los Rios comunas driven by the City-Funder Matching Engine's SINIM/FCM capacity (locode-keyed), badged real/estimated/intake; funders-open, transport gap, and pool from its CSVs. - Verified: prod build passes, pages serve 200, handoff POST->GET round-trips. - Valdivia: Ready (71) but sub-scale alone -> pool unit 11 (US$30M) -> eligible -> lands in pipeline. 'The gap becomes the deal.' Phase 4 (CityCatalyst module embed: OAuth, live city context, HIAP) is next. Also corrects the PRD's Valdivia locode to CL ZAL. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Maps every review point into decisions/tasks across content, logic, design, architecture, UX: enter-from-CityCatalyst provenance (inventory+HIAP), per-action Discover, Navigator<->Project Preparator boundary (shared readiness engine, two altitudes), instrument-specific readiness framing, shared @oef/readiness package, merged Build-readiness step, portfolio/pooling reframe, instrument eligibility, machine-readable candidate dossier into Intake & Triage, Results & Board rename. Includes a textual architecture map to seed the diagram (built after this push). Co-Authored-By: Claude Opus 4.8 <[email protected]>
…two-layer model) After reviewing the Project Preparator POC, CAPAG (Brazil Treasury creditworthiness for 5,570 munis), and the City-Funder Matching Engine: - INTEGRATED-ARCHITECTURE.md: two readiness layers (project bankability vs entity creditworthiness), country-specific Fiscal Data Adapters (CAPAG/SINIM keyed by locode), shared readiness package, Concept-Note-as-dossier, module boundaries. - ITERATION-2.1-PLAN.md: supersedes v2; positions the city app as the entity/ instrument/portfolio layer consuming prepared projects; adds the Fiscal Data Adapter + a Brazilian CAPAG hero city; plus a thin IDB-facing language upgrade for the SFP Control Tower (define acronyms once, rename 'M&E & Board' -> 'Results & Board Reporting', tab subheads, geography, dossier intake). Co-Authored-By: Claude Opus 4.8 <[email protected]>
…ntity-first, readiness-pathways, AI-agent context, M&E kept explicit - Add canonical Mermaid diagram to INTEGRATED-ARCHITECTURE.md (single-vertical Navigator ①->②, Path A into step ②, Matching as shared core service, capacity-building branch, AI-agent shared context). - ITERATION-2.1-PLAN §F/G/H: matching is a core service (both altitudes); 'Path B' renamed entity-first; capacity-building is a support branch not an entry; 'Build readiness' -> 'Readiness pathways' (assess+route); geographic/map view; left-hand process menu; dual-entry import/interoperability; AI-agent shared-context as a first-class requirement; explicit build pathway. - Keep M&E explicit (Monitoring & Evaluation) per IDB familiarity + team's work. Co-Authored-By: Claude Opus 4.8 <[email protected]>
… dossier, Control Tower copy
City Readiness Navigator (major evolution):
- Left-hand process menu (Explore -> City context -> Readiness pathways ->
Portfolio -> Funder intake), single-vertical journey.
- Fiscal Data Adapters: Chile (SINIM/FCM) + Brazil (CAPAG/Tesouro Nacional,
real RS data); interactive Leaflet choropleth of readiness, zoom to hero cities.
- Two-country, two-pathway demo: Valdivia (Ready -> pool -> IDB SFP) and Canoas
(CAPAG C, flood-hit -> capacity-building track, not a debt problem).
- Readiness pathways = assess + route (instrument / pool / capacity-building).
- CityCatalyst context seam (simulated inventory + HIAP + agent assist), ready
for live MCP.
- Candidate dossier (Concept Note + creditworthiness + pool + due diligence)
-> funder intake pipeline view.
- Polished CityCatalyst-styled UI; dev indicator disabled.
Control Tower: thin IDB-facing copy upgrade — orientation banner ('what this is'),
acronym glosses (SNG, sovereign guarantee, OVE, TC, Subprograms), and the tab
renamed to 'Monitoring & Evaluation (M&E) & Board' (kept explicit).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
- INTEGRATED-ARCHITECTURE.md §5a: Preparator as a peer module on the CityCatalyst host; Navigator as a 3-step vertical (creditworthiness → readiness pathways/coaching → portfolio & pooling); capacity building as a standalone support track (no longer wired into the Preparator). - PRD: new §1a "two-layer model" reframe; journey steps aligned (Choose the instrument, Readiness pathways, dossier, dual entry). - diagrams/: standalone SVGs for presenting (5a module view + process timeline) + README; the mermaid stays the source of truth. Co-Authored-By: Claude Opus 4.8 <[email protected]>
- Add README.md as the branch map (reading order, the two apps and where each lives, canonical vs superseded, the one-line model). - archive/ ← ITERATION-2-PLAN.md (superseded), ROADMAP.md (historical) - reference/ ← IDB program PDF, idb.txt, teammembers.md - control-tower/ ← SPEC.md + IMPLEMENTATION_PLAN.md (the app's own docs; fixes SPEC's relative links) and Mirco's M&E framework (Monitoring_Evaluation.md, MandE-questions.md) brought over from justagiraffe/mr/working-branch so his work is present on this branch. - Fix all internal links affected by the moves; drop vestigial .gitkeep. Note: Mirco's control-tower index.html/scoring.js edits were NOT merged — this branch's scoring.js is the newer profile-driven engine, and his versions contained no M&E-unique logic (the M&E substance is the two .md files above). His code edits are superseded, not lost. Co-Authored-By: Claude Opus 4.8 <[email protected]>
The team folder is now self-contained: city-readiness-navigator/ and control-tower/ sit as siblings under justagiraffe/, alongside the docs. Rationale: there is no workspace/build tooling that requires apps/ (it's an inconsistently-followed convention — civic-climate-action split the same way on main), and main is shared by every team's branch, so a single team-named folder avoids collisions and reviews as one unit. - git mv apps/city-readiness-navigator -> justagiraffe/city-readiness-navigator - Fix path refs in README, INTEGRATED-ARCHITECTURE, and the app's own README. - apps/ now holds only the shared _template. Co-Authored-By: Claude Opus 4.8 <[email protected]>
…yer, intra/cross portfolio
From Martin's v2.1 review:
- New 'Choose instrument' step between context and readiness ('readiness against
whom?') — IDB SFP card with the 'direct line' eligibility note; entity- vs
project-first framing; CAF/WB/GCF as template.
- Explore: upstream 'identity & context come from CityCatalyst' framing; a
State/region vs Cities view toggle with a region readiness summary; a data-source
toggle (current source + 'Import data…').
- City context enriched: GHG inventory + CCRA + HIAP + climate plan; project-first
shows an 'import project from Preparator' affordance.
- Portfolio now distinguishes INTRA-city (the city's own project pipeline pooled to
the ticket) vs CROSS-city pooling (with neighbours, showing their readiness).
- Six-stage left menu; dossier/submit handle all three pathways.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
…ce-readiness naming - Reflect the built v2.2 Navigator (6-stage flow, CAPAG+SINIM adapters, map, state/region toggle, instrument step, intra/cross portfolio, dossier, agent seam, Valdivia/Canoas pathways); update 'what's real vs to-build'. - Naming note: this is finance / climate-finance readiness, not generic 'readiness'. - Funder hierarchy: funder/bank -> program -> instrument. SFP is a PROGRAM, not an instrument; 'Choose instrument' should become a funder navigator drilling the hierarchy, fed by a converged funder sourcing service (today fragmented). Captured in architecture §4.3 + PRD §0/§4. Co-Authored-By: Claude Opus 4.8 <[email protected]>
justagiraffe/deck/index.html — a single-file, dependency-free slide deck (opens by double-click; arrow keys / space to navigate, f = fullscreen, n = speaker notes). 9 slides: problem → the two apps → dossier handoff → the 5a architecture SVG → the process-timeline SVG → how the other hackday projects plug in → revenue → demo close (Valdivia Ready / Canoas CAPAG-C). Both diagrams are inlined for portability; theme matches the SVG palette. Co-Authored-By: Claude Opus 4.8 <[email protected]>
- 'Choose instrument' -> 'Find financing': a 3-level funder navigator that drills funder -> program -> instrument (src/lib/funders.ts). IDB -> SFP (a PROGRAM) -> investment loan / guarantee / TC. CAF/WB/GCF shown as templates. Selecting a program sets the readiness profile; the dossier carries the full instrument label. Framed as fed by a 'funder sourcing service' (converged catalog, mock for now). - Naming: app is now 'Climate-Finance Readiness Navigator' (sidebar + metadata) so 'readiness' reads as finance/climate-finance readiness, not generic. Co-Authored-By: Claude Opus 4.8 <[email protected]>
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.
Builds on @mirco's stage-split branch. Two additions, both additive — the IDB demo behaves exactly as before.
1. Readiness engine is now pluggable per MDB
The eligibility logic that was hardcoded in
scoring.js(pillars, weights, tiers, the §4.3 project gate, the OP-301 checklist) is extracted into a readiness profile — a plug-in describing one funder's criteria.control-tower/readiness-profiles.js— registry + schema. IDB SFP is profile CAPAG Funder Scan — Unlock the Money hackday #1 (exact prior criteria); a clearly-labeled illustrative template shows how CAF / World Bank / EIB / GCF plug in.control-tower/scoring.js— derives weights/tiers/gate/checklist from the active profile. Every export + return shape unchanged.control-tower/index.html— one added<script>tag (loads the registry beforescoring.js).control-tower/READINESS-PROFILES.md— schema, how to add an MDB, and the signal mapping from the City-Funder Matching Engine's locode-keyed capacity data.Verified: a Node harness compared old vs new across all 63 SNGs — 567 assertions, 0 diffs (composite, tier, eligibility, checklist, blockers, canEnterProjectReview, action, explainScore, full scoreSNG). Profile-switching is reversible.
Why: readiness is target-specific (you're ready for a specific instrument), which makes it the bridge between the City-Funder Matching Engine and any funder's pipeline — and turns this from an IDB tool into the readiness layer for any MDB.
2. City-facing app PRD
justagiraffe/PRD-city-facing-readiness-app.md— build-ready spec for a CityCatalyst Journey Navigator module implementing the 7-step journey (discover → pick target → diagnose readiness → prepare → pool → submit). Grounded in a primary-source review of CityCatalyst's module model, OAuth 2.0/PKCE, HIAP prioritizer, and Global Data API. Honest [VERIFY] flags where source couldn't confirm.🤖 Generated with Claude Code