tokens-for-good 0.4.2 → 0.4.3

package/README.md

@@ -60,7 +60,11 @@ Once installed, these are available to your AI via the MCP server:
 - **OpenCode** — `init` writes `~/.config/opencode/opencode.json` and prints a cron line you can paste into `crontab -e`.
 - **Cursor / Windsurf / Devin** — `init` writes the MCP config; automation requires platform-native scheduling.
 
-## Development
+## Contributing
+
+TFG has been built and tested primarily on **Claude Code**. Making it work well on other harnesses — OpenCode, Cursor, Windsurf, Devin, anything else with MCP support — is the biggest open area for external help. See [CONTRIBUTING.md](CONTRIBUTING.md) for a tour of the code, the specific touch points a harness port needs to hit (`src/platform.js`, `src/init.js`, the session-start hook, and the skill files), and the local testing pattern.
+
+For quick dev setup:
 
 ```bash
 git clone https://github.com/Tokens-for-Good/tokens-for-good

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokens-for-good",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "type": "module",
   "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
   "bin": {

package/pipeline/01-research/PROMPT.md

@@ -53,8 +53,19 @@ List the top 20 negative consequences of that social problem for that population
 #### PROMPT 3 — Intermediary vs Ultimate Outcome Classification
 
 Keep all 20 items. Add a column classifying each as Intermediary or Ultimate Outcome.
-- **Intermediary:** changes in behavior or action from gains in knowledge, skills, or attitudes
-- **Ultimate:** changes in condition or life status (reduced poverty, improved health, economic stability)
+
+**Definitions:**
+- **Intermediary:** changes in behavior, action, or resources that result from the intervention but don't yet prove lives improved (e.g., increased income, employment, school enrollment, access to healthcare, consumption)
+- **Ultimate:** changes in condition or life status that directly reflect well-being improvements (e.g., improved health, housing security, quality of life, food security)
+
+**Edge cases — apply these exactly:**
+- Getting healthcare = Intermediary. Health actually improving = Ultimate.
+- Income going up = Intermediary. Using that income to improve housing, education, or health = Ultimate.
+- Moving out of poverty = Intermediary. Well-being or quality of life improving because of it = Ultimate.
+- Increased farm yield = Intermediary. Enhanced food security = Ultimate.
+- Increased access to most anything = Intermediary (we don't know if life improved because of that access).
+- School learning outcomes or completing school = Intermediary. Quality of life changing due to a better job from those outcomes = Ultimate.
+- Asset changes = Intermediary unless we know specifically what the asset is and how it improves life (safer housing, a latrine, durable productive tools = Ultimate; generic "asset score" or "asset holdings" = Intermediary).
 
 Sort by Intermediary first, then Ultimate.
 
@@ -83,36 +94,33 @@ Keep the table with ALL previous columns. For each of the 20 negative consequenc
 
 Write a recommendation (2-4 sentences): lead with stance, state strongest evidence, note caveats if any.
 
-Then include this scored checklist. Base score is out of 100. Counterfactuals are extra credit (max 120).
+**Section 2 — Scorecard**
 
-Base score (out of 100):
 - [x] or [ ] a. Has Ultimate Outcome Goals (50 pts)
 - [x] or [ ] b. Measures Intermediate Outcomes (10 pts)
 - [x] or [ ] c. Measures Ultimate Outcomes (15 pts)
 - [x] or [ ] d. Shows Continual Learning & Adaptation (25 pts)
-
-Extra credit:
 - [x] or [ ] e. Measures Intermediate Counterfactual (10 pts)
 - [x] or [ ] f. Measures Ultimate Counterfactual (10 pts)
 
-**Score: [X]/100** (can exceed 100 with extra credit, max 120)
+**Score: [X]/120**
 
-**Section 2 — The Social Problem**
+**Section 3 — The Social Problem**
 Frame with specificity ("chronic malnutrition among children under 5 in rural sub-Saharan Africa", not just "poverty"). Include scale and cite prevalence data.
 
-**Section 3 — The Solution**
+**Section 4 — The Solution**
 What the organization actually does (not their mission statement). Explain the theory of change: how does activity X lead to outcome Y? Be specific about the intervention.
 
-**Section 4 — Key Outputs**
+**Section 5 — Key Outputs**
 Measured activities and direct products with specific numbers. Distinguish outputs (things produced) from outcomes (changes caused).
 
-**Section 5 — Key Intermediate Outcomes**
+**Section 6 — Key Intermediate Outcomes**
 Measurable short-to-medium term changes. Note whether data is self-reported or independently verified. Include any counterfactual data found.
 
-**Section 6 — Key Ultimate Outcomes**
+**Section 7 — Key Ultimate Outcomes**
 Long-term impact evidence only. This section may be thin. Do not pad it. If no ultimate outcome data exists, say so in one sentence.
 
-**Section 7 — Continual Learning & Adaptation**
+**Section 8 — Continual Learning & Adaptation**
 Documented program changes based on evidence. "They adapted" needs specifics: what changed, based on what data, when?
 
 #### SOURCES
@@ -147,7 +155,7 @@ Run these checks before submitting. They are not optional.
 
 **Structure:**
 - [ ] All 5 prompt tables present and complete (20 rows each)
-- [ ] All 7 summary sections present with substantive content
+- [ ] All 8 summary sections present with substantive content
 - [ ] SOURCES section lists every URL cited inline
 - [ ] Scored checklist adds up correctly
 
@@ -164,6 +172,7 @@ Run these checks before submitting. They are not optional.
 - [ ] Replace "leverage" with "use", "utilize" with "use"
 - [ ] Paragraphs under 4 sentences
 - [ ] No superlatives unless backed by comparative data
+- [ ] Every acronym defined in full before first use (e.g., "Randomized Controlled Trial (RCT)" not just "RCT")
 
 ### 5. Submit
 

package/pipeline/04-peer-review/PROMPT.md

@@ -31,7 +31,7 @@ Pick 3-5 citation URLs from the report (prioritize any flagged by the automated
 
 Verify:
 - [ ] All 5 prompt sections present (PROMPT 1-5) with 20 rows each
-- [ ] All 7 summary sections present (Sections 1-7)
+- [ ] All 8 summary sections present (Sections 1-8)
 - [ ] SOURCES section exists with citations
 - [ ] Every factual claim has its own inline citation `[Source Name](URL)`
 - [ ] No claims cited to general overview pages when a specific report or data page exists
@@ -40,17 +40,14 @@ Verify:
 
 The scored checklist uses these weights. Verify the math and the evidence:
 
-Base score (out of 100):
 - a. Has Ultimate Outcome Goals (50 pts)
 - b. Measures Intermediate Outcomes (10 pts)
 - c. Measures Ultimate Outcomes (15 pts)
 - d. Shows Continual Learning & Adaptation (25 pts)
-
-Extra credit:
 - e. Measures Intermediate Counterfactual (10 pts)
 - f. Measures Ultimate Counterfactual (10 pts)
 
-**Score: X/100** (can exceed 100 with extra credit, max 120)
+**Score: X/120**
 
 Check:
 - Are checked items supported by evidence in the report?
@@ -65,6 +62,7 @@ Check:
 - Sections that are empty or trivially short
 - Claims that contradict other parts of the report
 - Em dashes, filler adjectives (robust, comprehensive, innovative), AI transitions
+- Acronyms used before being defined in full (e.g., "RCT" without first writing "Randomized Controlled Trial (RCT)")
 
 ### 7. Assign a Score
 

package/pipeline/_archive/2026-05-07-pre-todd-v2/01-research-PROMPT.md

@@ -0,0 +1,170 @@
+# Research an Organization for Fierce Philanthropy
+
+## Your Role
+
+You are a social impact research analyst for Fierce Philanthropy. You evaluate nonprofit organizations using Todd Manwaring's Social Impact Evaluation Framework. You are thorough, evidence-driven, and honest about what the data does and does not show.
+
+## Instructions
+
+### 1. Research the Organization
+
+Using web search and web fetch, thoroughly research:
+
+1. **The org's website** — homepage, about page, impact/results pages, annual reports
+2. **Impact evidence** — published data, metrics, program evaluations
+3. **Independent evaluations** — RCTs, quasi-experimental studies (search J-PAL, 3ie, Campbell Collaboration)
+4. **Third-party reviews** — GiveWell, Charity Navigator, GuideStar/Candid, news coverage
+5. **Financial data** — ProPublica Nonprofit Explorer (search by EIN or name), Form 990
+
+**Research rules:**
+- Only include DIRECT results from this organization or independent measurements of it
+- Only include measured results with citations. No anecdotes, no modeling, no evidence from other organizations.
+- Every factual claim must trace to a specific source URL you actually visited
+
+### 2. Generate the Report
+
+Follow this exact structure:
+
+---
+
+```
+# [Org Name] - Fierce Philanthropy Research Report
+
+**Date:** [today's date]
+**Methodology:** Todd Manwaring's Social Impact Evaluation Framework
+**Organization:** [Org Name]
+```
+
+---
+
+#### PROMPT 1 — Organization and Social Problem Summary
+
+1. **Social Problem:** (less than 5 words)
+2. **Population:** (who is affected)
+3. **Location:** (where)
+
+#### PROMPT 2 — Top 20 Negative Consequences
+
+| # | Negative Consequence |
+|---|----------------------|
+
+List the top 20 negative consequences of that social problem for that population in that location.
+
+#### PROMPT 3 — Intermediary vs Ultimate Outcome Classification
+
+Keep all 20 items. Add a column classifying each as Intermediary or Ultimate Outcome.
+- **Intermediary:** changes in behavior or action from gains in knowledge, skills, or attitudes
+- **Ultimate:** changes in condition or life status (reduced poverty, improved health, economic stability)
+
+Sort by Intermediary first, then Ultimate.
+
+#### PROMPT 4 — Positive Results Shared by Organization
+
+Keep the table with all columns. For each of the 20 negative consequences, add a column: does the organization share positive results?
+
+- Start each cell with "Yes.", "Partial.", or "No direct results shared."
+- When Yes or Partial: include SPECIFIC data (percentages, sample sizes, time periods, study names)
+- Only direct results from this organization, not from other orgs or modeling
+- **CITATION RULES (critical):** Every data point MUST have its own inline citation `[Source Name](URL)`. If one cell contains two facts from different sources, include two separate citations. Never cite a general overview page for a specific statistic — cite the exact page where you found the number.
+- **VERIFY INLINE:** After writing each cell, re-read the source you cited and confirm the exact numbers match. If the source says 75% and you wrote 59%, fix it before moving on. Do not proceed to the next row until the current row's numbers are confirmed against the cited page.
+
+#### PROMPT 5 — Counterfactual Results
+
+Keep the table with ALL previous columns. For each of the 20 negative consequences, add a column: does the organization share COUNTERFACTUAL results?
+
+- Start each cell with "Yes.", "Partial.", or "No counterfactual results."
+- Describe study design (RCT, quasi-experimental, matched comparison), sample sizes, what the control/comparison group showed
+- Counterfactual = comparison to what would have happened without the intervention. Before/after alone does not count.
+- **Same citation and verify-inline rules as Prompt 4:** every data point gets its own inline citation, and confirm numbers match the source before moving to the next row.
+
+#### SUMMARY REPORT
+
+**Section 1 — Our Recommendation**
+
+Write a recommendation (2-4 sentences): lead with stance, state strongest evidence, note caveats if any.
+
+Then include this scored checklist. Base score is out of 100. Counterfactuals are extra credit (max 120).
+
+Base score (out of 100):
+- [x] or [ ] a. Has Ultimate Outcome Goals (50 pts)
+- [x] or [ ] b. Measures Intermediate Outcomes (10 pts)
+- [x] or [ ] c. Measures Ultimate Outcomes (15 pts)
+- [x] or [ ] d. Shows Continual Learning & Adaptation (25 pts)
+
+Extra credit:
+- [x] or [ ] e. Measures Intermediate Counterfactual (10 pts)
+- [x] or [ ] f. Measures Ultimate Counterfactual (10 pts)
+
+**Score: [X]/100** (can exceed 100 with extra credit, max 120)
+
+**Section 2 — The Social Problem**
+Frame with specificity ("chronic malnutrition among children under 5 in rural sub-Saharan Africa", not just "poverty"). Include scale and cite prevalence data.
+
+**Section 3 — The Solution**
+What the organization actually does (not their mission statement). Explain the theory of change: how does activity X lead to outcome Y? Be specific about the intervention.
+
+**Section 4 — Key Outputs**
+Measured activities and direct products with specific numbers. Distinguish outputs (things produced) from outcomes (changes caused).
+
+**Section 5 — Key Intermediate Outcomes**
+Measurable short-to-medium term changes. Note whether data is self-reported or independently verified. Include any counterfactual data found.
+
+**Section 6 — Key Ultimate Outcomes**
+Long-term impact evidence only. This section may be thin. Do not pad it. If no ultimate outcome data exists, say so in one sentence.
+
+**Section 7 — Continual Learning & Adaptation**
+Documented program changes based on evidence. "They adapted" needs specifics: what changed, based on what data, when?
+
+#### SOURCES
+
+List all cited sources with full URLs:
+1. [Source Name](Full URL) - Brief description of what was cited
+2. ...
+
+End with: *Report prepared using Todd Manwaring's Social Impact Evaluation Framework for Fierce Philanthropy.*
+
+---
+
+### 3. Citation Rules (Read Carefully)
+
+These rules are critical for report quality. Poorly attributed citations are the #1 reason reports fail review.
+
+1. **One citation per fact.** If a sentence contains two claims from different sources, it needs two citations. Never bundle multiple facts under one link.
+
+2. **Cite the specific page, not a general overview.** If you found "27% reduction" on the org's 2024 Annual Report page, cite that URL — not their homepage or about page.
+
+3. **If you can't find a URL for a claim, don't include the claim.** No unsourced facts. If you read something during research but can't trace it to a specific page, leave it out.
+
+4. **Verify numbers match the source exactly.** After writing a claim with a number (percentage, dollar amount, count), re-read the cited page and confirm the exact figure appears there. Common errors: writing 59% when the source says 75%, writing 4,000 when the source says 1,651, or writing 20% when the source says 25%. If your number doesn't match, use the source's number or remove the claim.
+
+5. **Attribution matters.** Say "X reports that" when citing an org's own claims. Say "independent evaluation found" when citing third-party evidence. The distinction is load-bearing.
+
+6. **Format:** `[Source Name](URL)` inline. The SOURCES section at the end must list every URL cited in the report.
+
+### 4. Before-Submission Quality Checks
+
+Run these checks before submitting. They are not optional.
+
+**Structure:**
+- [ ] All 5 prompt tables present and complete (20 rows each)
+- [ ] All 7 summary sections present with substantive content
+- [ ] SOURCES section lists every URL cited inline
+- [ ] Scored checklist adds up correctly
+
+**Citations:**
+- [ ] Every factual claim has its own inline citation
+- [ ] Spot-check at least 5 citations: visit the URL and confirm the EXACT numbers on the page match what you wrote. If the source says 132% and you wrote 136%, fix it.
+- [ ] For any citation where the page doesn't support your claim, find the correct source or remove the claim
+- [ ] No claims are cited to general overview pages when a specific report or data page exists
+
+**Writing style:**
+- [ ] No em dashes (—). Replace with periods, commas, or parentheses.
+- [ ] No filler adjectives: seamless, robust, comprehensive, innovative, cutting-edge, holistic, game-changing
+- [ ] No AI transitions: "It's worth noting", "Here's the thing", "Let's dive in", "Simply put"
+- [ ] Replace "leverage" with "use", "utilize" with "use"
+- [ ] Paragraphs under 4 sentences
+- [ ] No superlatives unless backed by comparative data
+
+### 5. Submit
+
+Submit using `submit_report` with the full markdown as `report_markdown`. Include `estimated_tokens` (count web searches at ~1K tokens each, web fetches at ~2-5K each, your output at ~4 tokens/word, plus ~10K overhead).

package/pipeline/_archive/2026-05-07-pre-todd-v2/02-verify-PROMPT.md

@@ -0,0 +1,69 @@
+# Verify Citations (Standalone Re-verification)
+
+Use this methodology when re-verifying an existing report. During normal research, citation verification is built into the research prompt (Section 4, quality checks). This standalone step is for when a report needs a second verification pass.
+
+## Instructions
+
+### 1. Read the Report
+
+Read the full research report. Note every inline citation `[Source Name](URL)` and every factual claim.
+
+### 2. Test Every Citation
+
+For each citation, visit the URL using web fetch and verify:
+
+- **URL loads** — Is it a real page (not 404, not a redirect to a homepage)?
+- **Content matches** — Does the page actually say what the report claims? Quote the relevant passage.
+- **Data is accurate** — Do the numbers match?
+
+Record each check:
+
+| # | Citation | URL Status | Content Match | Notes |
+|---|----------|-----------|---------------|-------|
+
+Status values:
+- **VALID** — URL loads and content matches
+- **BROKEN** — 404 or page doesn't load
+- **MISMATCH** — URL loads but doesn't support the claim
+- **PARTIAL** — Some claims match, some don't
+- **UNVERIFIABLE** — Paywalled or content not accessible
+
+### 3. Re-attribute Mismatches
+
+For each MISMATCH or PARTIAL citation:
+1. Use web search to find the correct source for the claim
+2. If found: replace the citation URL with the correct one
+3. If not found anywhere: remove the claim from the report or add a caveat ("This claim could not be independently verified")
+
+Do not leave misattributed citations in place.
+
+### 4. Check for Hallucinations
+
+Search the web for claims that seem unusually specific:
+- Statistics that don't appear in any source
+- Named studies or RCTs that can't be found
+- Program details that contradict other sources
+
+### 5. Apply Corrections
+
+For each issue:
+
+```
+### Correction [N]
+**Location:** [First ~10 words of the problematic passage]
+**Problem:** [What's wrong]
+**Fix:** [What was changed]
+```
+
+### 6. Output
+
+Write the corrected report with a verification summary at the top:
+
+```markdown
+## Verification Summary
+- Citations checked: X
+- Valid: X | Broken: X | Mismatch: X | Partial: X
+- Claims removed (unsourced): X
+- Citations re-attributed: X
+- Corrections applied: X
+```

package/pipeline/_archive/2026-05-07-pre-todd-v2/03-humanize-PROMPT.md

@@ -0,0 +1,143 @@
+# Step 3: Humanize — Claude Code Instructions
+
+## Inputs
+
+- **Org name:** `{{ORG_NAME}}`
+- **Verified report:** The verified report from Step 2 (kept in memory from the previous step)
+- **Writing style guide:** The AI decontamination rules below
+
+## Purpose
+
+Step 2 verified the facts. This step makes the report sound human. You are an editor whose only job is to remove AI writing patterns and inject natural voice. Do not change the report structure, tables, checklist items, scores, or citations. Edit the prose only.
+
+## Instructions
+
+### 1. Read the Report and Style Guide
+
+Read the verified report (skip the verification log header, work on the content below the `---`).
+
+The AI decontamination passes below are your checklist.
+
+### 2. Run Each Pass
+
+Work through these checks in order. For each issue found, fix it and log the change.
+
+#### Pass 1: Em Dash Removal
+- Search for every `—` (em dash) in the content
+- Replace each with a period (two sentences), comma, or parentheses
+- Two short sentences almost always beat one em-dashed sentence
+- Log count: "Removed X em dashes"
+
+#### Pass 2: Sentence Rhythm
+- Flag where 3+ consecutive sentences are roughly the same length (within ~5 words)
+- Fix by splitting, combining, or varying structure
+- Goal: rhythm should vary when read aloud. Short. Then longer. Then medium.
+- Log: "Varied sentence rhythm in X sections"
+
+#### Pass 3: Paragraph Cadence
+- Flag sections where consecutive paragraphs follow the same structure (claim then explanation then example, repeated)
+- Vary the pattern: lead with evidence sometimes, skip the explanation, open with a question
+- Log: "Restructured X paragraphs for cadence variety"
+
+#### Pass 4: Opening Word Diversity
+- Scan every paragraph's first word. Flag 2+ consecutive paragraphs starting with the same word
+- Common offenders: "The...", "This...", repeated org name, "Pawsperity..." three times in a row
+- Rewrite at least one opener in each flagged group
+- Log: "Diversified openings in X locations"
+
+#### Pass 5: AI Pattern Scan
+Check for and fix:
+- [ ] "[Statement]. Not because X — because Y." dramatic structure
+- [ ] "Not just X, but Y" emphasis pattern
+- [ ] "Whether X or Y" parallel constructions
+- [ ] "From X to Y" range statements
+- [ ] "Here's the thing" / "Let's dive in" / "In short" / "Put simply" / "The reality is"
+- [ ] "At its core" / "At the end of the day" / "Fundamentally" as intensifier
+- [ ] "It's worth noting that" / "Importantly" at sentence start
+- [ ] Overused dramatic colon reveals
+- [ ] Overused semicolons
+- Log each pattern found and fixed
+
+#### Pass 6: Perfect Parallelism Breaker
+- Find bullet lists where every bullet follows the exact same grammatical structure
+- Vary at least one item's structure (not just words)
+- Don't always group in threes
+- Log: "Broke parallelism in X lists/sections"
+
+#### Pass 7: Filler Adjective Sweep
+Search for and remove/replace:
+- "seamless," "robust," "comprehensive," "critical," "fundamental," "innovative," "powerful," "unique," "holistic," "cutting-edge," "game-changing," "revolutionary"
+- "leverage" → "use", "utilize" → "use"
+- Remove minimizers: "simply," "just," "easily"
+- Usually the sentence is stronger without the adjective
+- Log: "Removed X filler adjectives"
+
+#### Pass 8: Read-Aloud Test
+- For each Summary Report section (Sections 1-7), simulate reading aloud
+- Flag anything that sounds stilted, overly formal, or robotically even
+- Rewrite flagged sentences to sound like a thoughtful analyst explaining to a colleague
+- Log: "Rewrote X sentences for natural voice"
+
+#### Pass 9: Voice Injection
+Add 2-3 human touches across the Summary Report sections:
+- Brief asides showing evaluator judgment ("This is a stronger evidence base than most organizations in this space provide.")
+- Concrete contextualization ("To put this in perspective, the WHO considers X to be the threshold for Y.")
+- Honest assessments where evidence is ambiguous ("The data here is suggestive but not conclusive.")
+- Do NOT overdo this. 2-3 per report max. They should feel like a thoughtful analyst's observations, not a personality transplant.
+- Log each injection with location and what was added
+
+### 3. Preserve Report Structure
+
+After all passes, verify you did NOT change:
+- [ ] Any markdown heading (##, ###)
+- [ ] Any table structure or table data
+- [ ] The scored checklist items or their checked/unchecked status
+- [ ] The score (X/100)
+- [ ] Citation URLs or citation text inside `[brackets](links)`
+- [ ] The SOURCES section
+- [ ] Section separators (`---`)
+
+### 4. Produce Output
+
+Keep the humanized report in memory. This is the final version that will be submitted via the `submit_report` tool.
+
+Start the output with a change log:
+
+```markdown
+<!-- Humanized: {{ORG_NAME}} | Date: [date] -->
+
+# Humanization Log
+
+## Changes by Pass
+- **Em dashes:** Removed [X] instances
+- **Sentence rhythm:** Varied in [X] sections
+- **Paragraph cadence:** Restructured [X] paragraphs
+- **Opening diversity:** Fixed [X] locations
+- **AI patterns:** Found and fixed: [list each pattern]
+- **Parallelism:** Broke in [X] lists/sections
+- **Filler adjectives:** Removed [X] ([list them])
+- **Read-aloud fixes:** Rewrote [X] sentences
+- **Voice injections:** Added [X] ([brief description of each])
+
+## Structure Verification
+- [ ] Headings unchanged
+- [ ] Tables unchanged
+- [ ] Checklist and score unchanged
+- [ ] Citations unchanged
+- [ ] Sources section unchanged
+
+---
+
+[Full humanized report below]
+```
+
+## Quality Checks
+
+Before writing the output:
+- [ ] Zero em dashes remain in the content
+- [ ] No two consecutive paragraphs start with the same word
+- [ ] No AI pattern from the tells list remains
+- [ ] At least 2 voice injections added (but no more than 3)
+- [ ] Report structure is identical to the input
+- [ ] Content reads like a human analyst wrote it
+- [ ] The change log accurately reflects all changes made

package/pipeline/_archive/2026-05-07-pre-todd-v2/04-peer-review-PROMPT.md

@@ -0,0 +1,93 @@
+# Peer Review — Instructions
+
+## Purpose
+
+You are reviewing another contributor's research report. Your job is to verify quality and catch problems before a human reviewer sees it. You are NOT the original researcher — you are a second pair of eyes.
+
+## Instructions
+
+### 1. Check the Automated Fact-Check Results First
+
+If automated fact-check results are included above the report, read them before diving into the report itself. Focus on:
+- **Red flags** — these are specific problems the automated system detected (unsupported claims, dead links, self-reported data issues)
+- **Fact support rate** — below 70% means many claims aren't backed by their cited sources
+- **Avg trust score** — below 50% means citations are low-quality (self-reported, blog posts, dead links)
+
+Use these results to target your spot-checks. If the automated system flagged specific unsupported claims, verify those first.
+
+### 2. Read the Full Report
+
+Read the entire report. Note the org name, the scored checklist, and the overall recommendation.
+
+### 3. Spot-Check Citations (3-5)
+
+Pick 3-5 citation URLs from the report (prioritize any flagged by the automated fact-check). For each:
+- Visit the URL using web fetch
+- Verify the page exists (not 404)
+- Check that the source says what the report claims
+- If a citation is wrong, search for the correct source. If the claim can't be sourced anywhere, remove it.
+
+### 4. Check Report Structure
+
+Verify:
+- [ ] All 5 prompt sections present (PROMPT 1-5) with 20 rows each
+- [ ] All 7 summary sections present (Sections 1-7)
+- [ ] SOURCES section exists with citations
+- [ ] Every factual claim has its own inline citation `[Source Name](URL)`
+- [ ] No claims cited to general overview pages when a specific report or data page exists
+
+### 5. Evaluate Scoring
+
+The scored checklist uses these weights. Verify the math and the evidence:
+
+Base score (out of 100):
+- a. Has Ultimate Outcome Goals (50 pts)
+- b. Measures Intermediate Outcomes (10 pts)
+- c. Measures Ultimate Outcomes (15 pts)
+- d. Shows Continual Learning & Adaptation (25 pts)
+
+Extra credit:
+- e. Measures Intermediate Counterfactual (10 pts)
+- f. Measures Ultimate Counterfactual (10 pts)
+
+**Score: X/100** (can exceed 100 with extra credit, max 120)
+
+Check:
+- Are checked items supported by evidence in the report?
+- Are unchecked items correctly unchecked (no evidence was found)?
+- Does the score math add up?
+
+### 6. Look for Red Flags
+
+- Suspiciously specific numbers with no citation
+- Studies or evaluations that seem fabricated
+- Copy-pasted content or generic filler
+- Sections that are empty or trivially short
+- Claims that contradict other parts of the report
+- Em dashes, filler adjectives (robust, comprehensive, innovative), AI transitions
+
+### 7. Assign a Score
+
+| Score | When to use |
+|-------|------------|
+| **4 — Great** | Report is thorough, citations check out, scoring is correct. No changes needed. |
+| **3 — Good with fixes** | Minor issues you can fix: broken citation, wrong score math, awkward phrasing, a checklist item that should be toggled, misattributed citation. **Fix the issues yourself** and submit the corrected report. |
+| **2 — Needs redo** | Major problems: thin evidence across multiple sections, significant hallucinations, missing sections, fundamentally wrong scoring. Not fixable with minor edits. |
+| **1 — Bad actor** | Garbage: copy-pasted nonsense, completely fabricated data, obvious gaming attempt. This flags the original author. Use sparingly and only when clearly warranted. |
+
+### 8. Submit Your Review
+
+Use `submit_peer_review` with:
+- `claim_id`: The claim ID shown above
+- `score`: Your score (1-4)
+- `notes`: Brief explanation of your score. Mention which citations you checked and what you found.
+- `updated_report`: If score is 3, include the full fixed report
+
+## Important Rules
+
+- Be fair. Most reports should score 3 or 4.
+- Score 2 is for genuinely bad reports, not minor style preferences.
+- Score 1 is for abuse. If you're unsure, use 2 instead.
+- If you spot-check a citation and it's broken, that alone is a 3 (fix it), not a 2.
+- Don't rewrite the report to match your style. Fix factual errors, not opinions.
+- If the automated fact-check flagged issues, verify them. If the flags are correct, fix the citations (score 3) or flag the report (score 2) depending on severity.

package/pipeline/_archive/2026-05-07-pre-todd-v2/README.md

@@ -0,0 +1,11 @@
+# Archive: Pre-Todd-v2 Prompts
+
+**Archived:** 2026-05-07  
+**Reason:** Updating methodology to incorporate Todd Manwaring's revised training & prompts (PDF: "2026 04 25 Training & Prompt.pdf")  
+**Restore:** Copy any file back to its corresponding `pipeline/0N-*/PROMPT.md` location
+
+## Files
+- `01-research-PROMPT.md` — Main research prompt (prompts 1-5 + summary)
+- `02-verify-PROMPT.md` — Citation re-verification
+- `03-humanize-PROMPT.md` — AI pattern removal
+- `04-peer-review-PROMPT.md` — Peer review scoring

package/src/api-client.js

@@ -86,11 +86,4 @@ export class ApiClient {
     return this.request('GET', '/research/impact');
   }
 
-  async getNextAction() {
-    return this.request('GET', '/research/next-action');
-  }
-
-  async enableSchedule() {
-    return this.request('POST', '/research/enable-schedule');
-  }
 }

package/src/init.js

@@ -174,7 +174,16 @@ function statePath()     { return homeRelative(join(homedir(), '.tokens-for-good
 
 function readJsonOrEmpty(path) {
   if (!existsSync(path)) return {};
-  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return {}; }
+  const raw = readFileSync(path, 'utf-8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `${path} exists but is not valid JSON.\n` +
+      `Fix or delete the file, then re-run init.\n` +
+      `(Tip: paste it into https://jsonlint.com to find the syntax error.)`
+    );
+  }
 }
 
 function ensureDir(path) {

package/src/mcp-server.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { ApiClient } from './api-client.js';
 import { detectPlatform, isSchedulable, getAutomationInstructions } from './platform.js';
-import { loadState, updateState, isSnoozed, hasContributedToday, markContributed, markSetupComplete } from './state.js';
+import { loadState, updateState, isSnoozed, snoozeDays, hasContributedToday, markContributed, markSetupComplete } from './state.js';
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -144,7 +144,7 @@ server.tool('submit_report', 'Submit a completed research report for an org you
   if (!client) return { content: [{ type: 'text', text: 'Error: TFG_API_KEY not set.' }] };
 
   try {
-    const result = await client.submitReport(claim_id, report_markdown, null, null, model_used, PKG_VERSION);
+    const result = await client.submitReport(claim_id, report_markdown, estimated_tokens, null, model_used, PKG_VERSION);
     markContributed();
 
     // One-off users: first successful submit completes their initial setup,
@@ -205,7 +205,7 @@ server.tool('get_peer_review', 'Get a draft report assigned to you for peer revi
 
 server.tool('submit_peer_review', 'Submit your peer review score for a report.', {
   claim_id: z.string().describe('The claim ID of the report being reviewed'),
-  score: z.number().min(1).max(4).describe('Score: 4=great, 3=good with fixes, 2=needs redo, 1=bad actor'),
+  score: z.number().int().min(1).max(4).describe('Score: 4=great, 3=good with fixes, 2=needs redo, 1=bad actor'),
   notes: z.string().optional().describe('Review notes explaining the score'),
   updated_report: z.string().optional().describe('If score is 3, the fixed version of the report'),
 }, async ({ claim_id, score, notes, updated_report }) => {
@@ -270,6 +270,13 @@ server.tool('mark_setup_complete', 'Called by the /tfg-schedule skill after /sch
   return { content: [{ type: 'text', text: 'Marked setup complete. The SessionStart hook will go silent from the next session.' }] };
 });
 
+server.tool('snooze', 'Snooze Tokens for Good reminders. Call this when the user says to remind them tomorrow, next week, or in N days.', {
+  days: z.number().int().min(1).max(365).describe('Days to snooze (1 = tomorrow, 7 = next week)'),
+}, async ({ days }) => {
+  snoozeDays(days);
+  return { content: [{ type: 'text', text: `Got it — Tokens for Good will stay quiet for ${days} day${days === 1 ? '' : 's'}.` }] };
+});
+
 // --- Prompts (session start) ---
 
 server.prompt('session_start', 'Check if you should research an org or complete a peer review', {}, async () => {
@@ -286,18 +293,16 @@ server.prompt('session_start', 'Check if you should research an org or complete
   const state = loadState();
 
   // Check for pending peer review first
-  if (client) {
-    try {
-      const review = await client.getNextPeerReview();
-      return {
-        messages: [{
-          role: 'user',
-          content: { type: 'text', text: `You have a pending peer review to complete before you can claim a new org. Use get_peer_review to see the report, then submit_peer_review with your score.` },
-        }],
-      };
-    } catch {
-      // No pending review, continue
-    }
+  try {
+    await client.getNextPeerReview();
+    return {
+      messages: [{
+        role: 'user',
+        content: { type: 'text', text: `You have a pending peer review to complete before you can claim a new org. Use get_peer_review to see the report, then submit_peer_review with your score.` },
+      }],
+    };
+  } catch {
+    // No pending review, continue
   }
 
   if (isSnoozed()) {

package/src/state.js

@@ -78,7 +78,3 @@ export function markSetupComplete() {
   updateState({ first_setup_complete: true });
 }
 
-export function isInitialized() {
-  const state = loadState();
-  return state.intended_flow !== null;
-}