erdos-problems 0.2.10 → 0.3.1

package/docs/DEEP_RESEARCH_BUNDLE_SPEC.md

@@ -0,0 +1,129 @@
+# Deep Research Bundle Spec
+
+Last updated: 2026-03-30
+
+## Purpose
+
+This document defines how `SproutSeeds/erdos-problems` can hold the full public research archive without forcing all of it into the npm package.
+
+The package should keep a two-speed model:
+
+- fast install and immediate dossier/pack handoff through npm
+- deeper public research bundles through the GitHub repo
+
+## Repo-only directories
+
+These directories are intended to live in the GitHub repo but stay out of the npm tarball:
+
+- `research/`
+- `formal/`
+- `paper/`
+- `imports/`
+- `analysis/`
+
+They remain repo-only by staying outside the `package.json` `files` list.
+
+## Recommended layout
+
+```text
+research/
+  problems/<id>/
+    README.md
+    boards/
+    checkpoints/
+    notes/
+    wave-history/
+
+formal/
+  lean/
+    README.md
+    SunflowerLean/
+
+paper/
+  README.md
+  problems/<id>/
+  references/
+
+imports/
+  README.md
+  external-atlas/
+  public-site/
+
+analysis/
+  README.md
+  problem20/
+  problem857/
+```
+
+## Problem handoff model
+
+Every serious problem should eventually have three public layers:
+
+### 1. Canonical dossier
+
+Lives in `problems/<id>/`.
+
+Use for:
+- source page
+- canonical local status
+- short statement
+- references
+- evidence ledger
+- formalization posture
+
+### 2. Public pack packet
+
+Lives in `packs/<family>/problems/<id>/`.
+
+Use for:
+- active route
+- current frontier
+- ready queue
+- checkpoint/report templates
+- concise operational handoff
+
+### 3. Deep research bundle
+
+Lives in `research/problems/<id>/`.
+
+Use for:
+- long-form notes
+- board exports
+- route decompositions
+- wave histories
+- intermediate artifacts
+- deeper public context not needed in the npm install
+
+## Formal bundle
+
+Formalization source should live under `formal/lean/` or another clearly scoped formal directory inside this repo.
+
+Pack packets may point into those repo-local formal files, but should not point back out to `sunflower-coda` once the migration is complete.
+
+## Paper bundle
+
+Paper drafts, publication notes, and public reference-reading order should live under `paper/`.
+
+The npm install does not need all of this by default, but the repo should be able to present it as part of the canonical public archive.
+
+For problem-specific writing, prefer `paper/problems/<id>/` bundles created by `erdos paper init <id>`.
+
+## Import bundle
+
+External imports should live under `imports/` when they are intentionally retained in the repo.
+
+These are not canonical dossier truth. They are imported provenance and reconciliation material.
+
+## Migration order
+
+1. store this directory contract in the repo
+2. create the repo-only directories with READMEs
+3. migrate flagship public materials for `20` and `857`
+4. update pack references from `sunflower-coda/...` to repo-local paths
+5. add CLI affordances for pointing users at the deeper repo-held bundles
+
+## Success criteria
+
+- the GitHub repo can hold the full public archive
+- npm remains focused on install-critical assets
+- a user can understand the shallow-to-deep handoff without guessing

package/docs/ERDOS_PROBLEMS_PROBLEM_SCHEMA.md

@@ -1,6 +1,6 @@
 # Erdos Problems Problem Schema
 
-Last updated: 2026-03-25
+Last updated: 2026-03-30
 
 ## Purpose
 
@@ -8,9 +8,9 @@ This schema defines the canonical local dossier record for each seeded problem i
 
 Goals:
 - every Erdős problem has a consistent local home
-- local dossier truth stays separate from upstream public truth
+- local dossier truth stays separate from imported public truth
 - agents can bootstrap from canonical artifacts immediately after install
-- pulled upstream/site bundles can be promoted into canonical dossiers without losing provenance
+- pulled import/site bundles can be promoted into canonical dossiers without losing provenance
 
 ## Canonical files
 
@@ -21,7 +21,7 @@ Each seeded problem should have:
 - `problems/<id>/EVIDENCE.md`
 - `problems/<id>/FORMALIZATION.md`
 
-Bundled upstream snapshot artifacts live in:
+Bundled import snapshot artifacts live in:
 - `data/upstream/erdosproblems/problems.yaml`
 - `data/upstream/erdosproblems/PROBLEMS_INDEX.json`
 - `data/upstream/erdosproblems/SYNC_MANIFEST.json`
@@ -40,15 +40,16 @@ Workspace-generated artifacts may live in:
 
 ## Canonical truth split
 
-External public truth:
-- tracked, not rewritten
-- upstream structured repo: `teorth/erdosproblems`
-- public presentation site: `erdosproblems.com`
-
-Local atlas truth:
+Canonical repo truth:
+- `SproutSeeds/erdos-problems`
 - `problems/<id>/problem.yaml`
 - dossier markdown files beside it
 
+External imported public truth:
+- tracked, not silently rewritten
+- external structured repo: `teorth/erdosproblems`
+- public presentation site: `erdosproblems.com`
+
 Local harness truth:
 - route state
 - evidence notes
@@ -67,7 +68,7 @@ source:
   site: "erdosproblems.com"
   url: "https://www.erdosproblems.com/857"
   external_id: "857"
-upstream:
+external_source:
   repo: "https://github.com/teorth/erdosproblems"
   data_file: "data/problems.yaml"
   number: "857"
@@ -75,8 +76,8 @@ status:
   site_status: "open"
   site_badge: "OPEN"
   repo_status: "active"
-  upstream_status: "open"
-  upstream_last_update: "2025-08-31"
+  imported_status: "open"
+  imported_last_update: "2025-08-31"
 cluster: "sunflower"
 prize:
   display: "no"
@@ -97,8 +98,8 @@ evidence_path: "EVIDENCE.md"
 formalization_path: "FORMALIZATION.md"
 formalization:
   status: "active"
-  upstream_state: "no"
-  upstream_last_update: "2025-08-31"
+  imported_state: "no"
+  imported_last_update: "2025-08-31"
 research_state:
   open_problem: true
   active_route: "anchored_selector_linearization"
@@ -115,7 +116,7 @@ provenance:
   seeded_at: "2026-03-25T..."
   seeded_from:
     kind: "pull_bundle"
-    upstream_record_included: true
+    imported_record_included: true
     site_snapshot_included: false
 ```
 
@@ -125,7 +126,7 @@ provenance:
 - `display_name`
 - `title`
 - `source`
-- `upstream`
+- `external_source`
 - `status`
 - `cluster`
 - `family_tags`
@@ -171,12 +172,18 @@ Repo-local examples:
 - `site-proved-lean`
 - `unstarted`
 
+## Legacy compatibility
+
+During migration, older dossiers may still use an `upstream` block instead of `external_source`.
+
+That legacy spelling should be treated as imported external provenance, not as a statement that another repo outranks the canonical local dossier.
+
 ## Scaffold contract
 
 `erdos scaffold problem <id>` should create a workspace-ready bundle containing:
 - copied canonical dossier files
 - `problem.yaml`
-- upstream record snapshot when available
+- imported record snapshot when available
 - pack README context when available
 - per-problem pack context when available
 - compute packets when available
@@ -188,7 +195,7 @@ Repo-local examples:
 - a root pull manifest
 - an `artifacts/` lane
 - a `literature/` lane
-- upstream record snapshot when available
+- imported record snapshot when available
 - local dossier artifacts when the problem is already seeded locally
 - optional live site snapshot and extracted text when `--include-site` is used
 
@@ -201,4 +208,4 @@ Repo-local examples:
 - `EVIDENCE.md`
 - `FORMALIZATION.md`
 
-The resulting dossier should preserve upstream/site provenance and be safe for later manual curation.
+The resulting dossier should preserve imported provenance and site provenance and be safe for later manual curation.

package/docs/ERDOS_PROBLEMS_REPO_SPEC.md

@@ -1,6 +1,6 @@
 # Erdos Problems Repo Spec
 
-Last updated: 2026-03-25
+Last updated: 2026-03-30
 
 ## Purpose
 
@@ -26,7 +26,7 @@ Targets:
 It is not:
 - a raw mirror of `sunflower-coda`
 - a generic research framework
-- a place where local route state silently overwrites public upstream truth
+- a place where local route state silently overwrites imported public evidence
 
 ## Core model
 
@@ -36,9 +36,9 @@ The repo has three layers.
 
 All seeded Erdős problems live here with canonical local dossiers.
 
-### 2. Upstream truth layer
+### 2. External import layer
 
-The package ships a bundled snapshot of `teorth/erdosproblems` and can refresh a workspace-local snapshot.
+The package can carry a bundled external atlas snapshot and refresh a workspace-local import snapshot for reconciliation and seeding.
 
 ### 3. Harness layer
 
@@ -56,9 +56,10 @@ The GitHub repo is the central public collaboration space.
 
 The npm package is the installable distribution channel, not the only collaboration surface.
 
-- the package ships the CLI, bundled upstream snapshot, canonical dossiers, and packaged pack assets
+- the package ships the CLI, bundled external import snapshot, canonical dossiers, and packaged pack assets
+- repo-only directories such as `research/`, `formal/`, `paper/`, `imports/`, and `analysis/` may hold deeper public material without shipping in npm
 - the public repo may also contain contribution guides, issue templates, maintainer notes, and other repo-only collaboration files that do not need to ship in the npm tarball
-- workspace-local upstream refreshes should be explicit and inspectable
+- workspace-local external imports should be explicit and inspectable
 
 ## Repository shape
 
@@ -81,6 +82,13 @@ erdos-problems/
       README.md
       problems/<id>/
       compute/<id>/
+  research/
+    problems/<id>/
+  formal/
+    lean/
+  paper/
+  imports/
+  analysis/
   data/upstream/erdosproblems/
   docs/
 ```
@@ -123,8 +131,8 @@ Each canonical seeded dossier contains:
 `erdos maintainer seed problem <id>` promotes a pulled bundle into a canonical local dossier.
 
 This is the disciplined bridge from:
-- public upstream/site truth
-- to local canonical dossier truth
+- imported public site / atlas evidence
+- to canonical local dossier truth
 
 ## Sunflower pack model
 
@@ -175,15 +183,16 @@ erdos sunflower status 857 --json
 
 ## Canonical truth split
 
-Public upstream truth:
+Canonical repo truth:
+- `SproutSeeds/erdos-problems`
+- `problems/<id>/problem.yaml`
+- dossier markdown files beside it
+
+External import sources:
 - `teorth/erdosproblems`
 - `data/problems.yaml`
 - `erdosproblems.com`
 
-Local atlas truth:
-- `problems/<id>/problem.yaml`
-- dossier markdown files beside it
-
 Local harness truth:
 - research state
 - checkpoints

package/docs/PAPER_WRITER_MODE.md

@@ -0,0 +1,118 @@
+# Paper Writer Mode
+
+Last updated: 2026-03-30
+
+## Purpose
+
+`erdos paper init <id>` creates or resumes a paper bundle for a problem.
+
+The goal is to make paper writing:
+
+- public-safe
+- claim-safe
+- citation-safe
+- resumable
+- legible to both humans and agents
+
+## Commands
+
+```bash
+erdos paper init [<id>] [--dest <path>] [--json]
+erdos paper show [<id>] [--dest <path>] [--json]
+```
+
+Behavior:
+
+- if run inside `SproutSeeds/erdos-problems`, the default bundle destination is `paper/problems/<id>/`
+- otherwise the default bundle destination is `.erdos/papers/<id>/`
+- rerunning `erdos paper init` updates the machine-readable indexes and fills missing files without overwriting existing section drafts
+
+## Bundle Contract
+
+Every initialized bundle includes:
+
+- `MANIFEST.json`
+- `PUBLIC_EVIDENCE_INDEX.json`
+- `SECTION_INDEX.json`
+- `README.md`
+- `WRITER_BRIEF.md`
+- `SECTION_STATUS.md`
+- `OUTLINE.md`
+- `STYLE_GUIDE.md`
+- `PRIVACY_REVIEW.md`
+- `CITATION_LEDGER.md`
+- section draft files
+
+Current section draft set:
+
+- `ABSTRACT.md`
+- `INTRODUCTION.md`
+- `PRELIMINARIES.md`
+- `RELATED_WORK.md`
+- `MAIN_RESULTS.md`
+- `PROOF_OVERVIEW.md`
+- `PROOF_DETAILS.md`
+- `COMPUTATIONAL_AND_FORMAL_EVIDENCE.md`
+- `LIMITATIONS_AND_OPEN_PROBLEMS.md`
+
+## Safety Model
+
+### Privacy
+
+The generated bundle should be safe to commit to the public repo.
+
+Rules:
+
+- no secrets
+- no credentials
+- no private correspondence
+- no local absolute filesystem paths
+- no unpublished private notes treated as paper evidence
+
+To support this, the generated indexes store repo-relative paths whenever possible and omit local-only paths from the committed data model.
+
+### Claim Safety
+
+The bundle assumes the paper may describe an open route rather than a finished proof.
+
+Rules:
+
+- theorem language only for claims actually supported by the current public record
+- computational evidence stays computational
+- formalization posture stays distinct from proof posture
+- open seams stay visible
+- unresolved tasks must land in `LIMITATIONS_AND_OPEN_PROBLEMS.md`
+
+### Citation Discipline
+
+External claims should enter the paper only through `CITATION_LEDGER.md`.
+
+Rules:
+
+- log the source before relying on it in prose
+- use exact identifiers whenever possible
+- treat imported atlas records as provenance, not canonical authority
+
+## Agent Workflow
+
+Recommended loop:
+
+1. Read `MANIFEST.json`.
+2. Read `PUBLIC_EVIDENCE_INDEX.json`.
+3. Read `SECTION_INDEX.json`.
+4. Update `OUTLINE.md` and `SECTION_STATUS.md`.
+5. Add external sources to `CITATION_LEDGER.md`.
+6. Draft or refine one section file at a time.
+7. Run the checklist in `PRIVACY_REVIEW.md` before release.
+
+## Current Scope
+
+This first slice gives the repo a structured paper-writing surface.
+
+It does not yet:
+
+- auto-import the full deep paper archive from `sunflower-coda`
+- auto-resolve literature citations from external databases into final bibliography form
+- emit a final LaTeX source tree or journal-targeted template
+
+Those are natural next steps once the deeper public research migration is in place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "erdos-problems",
-  "version": "0.2.10",
+  "version": "0.3.1",
   "description": "CLI atlas and workspace tools for Paul Erdos problems.",
   "type": "module",
   "bin": {

package/problems/1/AGENT_START.md

@@ -14,4 +14,4 @@ Working assumptions:
 - Harness depth: dossier
 
 First honest move:
-- tighten the local dossier for problem 1 against its pull bundle, references, and upstream provenance before widening claims.
+- tighten the local dossier for problem 1 against its pull bundle, references, and import provenance before widening claims.

package/problems/1/EVIDENCE.md

@@ -1,7 +1,7 @@
 # Evidence
 
 - This dossier was seeded for Erdos Problem #1 from a pull bundle.
-- Upstream record included: yes
+- Imported record included: yes
 - Site snapshot included: yes
 - Repo status at seed time: cataloged
 - Harness depth at seed time: dossier

package/problems/1/FORMALIZATION.md

@@ -1,8 +1,8 @@
 # Formalization
 
 - Local status: planned
-- Upstream formalized state: yes
-- Upstream formalized last update: 2025-08-31
+- Imported formalized state: yes
+- Imported formalized last update: 2025-08-31
 
 Seed note:
 - this file was created automatically from a pull bundle and should be upgraded as local formal work begins.

package/problems/1/problem.yaml

@@ -5,7 +5,7 @@ source:
   site: erdosproblems.com
   url: https://www.erdosproblems.com/1
   external_id: "1"
-upstream:
+external_source:
   repo: https://github.com/teorth/erdosproblems
   data_file: data/problems.yaml
   number: "1"
@@ -13,14 +13,14 @@ provenance:
   seeded_at: 2026-03-26T04:41:24.787Z
   seeded_from:
     kind: pull_bundle
-    upstream_record_included: true
+    imported_record_included: true
     site_snapshot_included: true
 status:
   site_status: open
   site_badge: OPEN
   repo_status: cataloged
-  upstream_status: open
-  upstream_last_update: 2025-08-31
+  imported_status: open
+  imported_last_update: 2025-08-31
 cluster: number-theory
 prize:
   display: $500
@@ -40,5 +40,5 @@ evidence_path: EVIDENCE.md
 formalization_path: FORMALIZATION.md
 formalization:
   status: planned
-  upstream_state: yes
-  upstream_last_update: 2025-08-31
+  imported_state: yes
+  imported_last_update: 2025-08-31

package/problems/1008/problem.yaml

@@ -5,7 +5,7 @@ source:
   site: erdosproblems.com
   url: https://www.erdosproblems.com/1008
   external_id: "1008"
-upstream:
+external_source:
   repo: https://github.com/teorth/erdosproblems
   data_file: data/problems.yaml
   number: "1008"
@@ -13,8 +13,8 @@ status:
   site_status: solved
   site_badge: PROVED (LEAN)
   repo_status: historical
-  upstream_status: proved (Lean)
-  upstream_last_update: 2026-01-17
+  imported_status: proved (Lean)
+  imported_last_update: 2026-01-17
 cluster: graph-theory
 prize:
   display: no
@@ -33,5 +33,5 @@ evidence_path: EVIDENCE.md
 formalization_path: FORMALIZATION.md
 formalization:
   status: site-proved-lean
-  upstream_state: no
-  upstream_last_update: 2025-09-10
+  imported_state: no
+  imported_last_update: 2025-09-10

package/problems/18/problem.yaml

@@ -5,7 +5,7 @@ source:
   site: erdosproblems.com
   url: https://www.erdosproblems.com/18
   external_id: "18"
-upstream:
+external_source:
   repo: https://github.com/teorth/erdosproblems
   data_file: data/problems.yaml
   number: "18"
@@ -13,8 +13,8 @@ status:
   site_status: open
   site_badge: OPEN
   repo_status: cataloged
-  upstream_status: open
-  upstream_last_update: 2025-08-31
+  imported_status: open
+  imported_last_update: 2025-08-31
 cluster: number-theory
 prize:
   display: no
@@ -34,5 +34,5 @@ evidence_path: EVIDENCE.md
 formalization_path: FORMALIZATION.md
 formalization:
   status: statement-formalized
-  upstream_state: yes
-  upstream_last_update: 2026-03-15
+  imported_state: yes
+  imported_last_update: 2026-03-15

package/problems/19/AGENT_START.md

@@ -14,4 +14,4 @@ Working assumptions:
 - Harness depth: dossier
 
 First honest move:
-- tighten the local dossier for problem 19 against its pull bundle, references, and upstream provenance before widening claims.
+- tighten the local dossier for problem 19 against its pull bundle, references, and import provenance before widening claims.

package/problems/19/EVIDENCE.md

@@ -1,7 +1,7 @@
 # Evidence
 
 - This dossier was seeded for Erdos Problem #19 from a pull bundle.
-- Upstream record included: yes
+- Imported record included: yes
 - Site snapshot included: yes
 - Repo status at seed time: cataloged
 - Harness depth at seed time: dossier

package/problems/19/FORMALIZATION.md

@@ -1,8 +1,8 @@
 # Formalization
 
 - Local status: planned
-- Upstream formalized state: no
-- Upstream formalized last update: 2025-08-31
+- Imported formalized state: no
+- Imported formalized last update: 2025-08-31
 
 Seed note:
 - this file was created automatically from a pull bundle and should be upgraded as local formal work begins.

package/problems/19/problem.yaml

@@ -5,7 +5,7 @@ source:
   site: erdosproblems.com
   url: https://www.erdosproblems.com/19
   external_id: "19"
-upstream:
+external_source:
   repo: https://github.com/teorth/erdosproblems
   data_file: data/problems.yaml
   number: "19"
@@ -13,14 +13,14 @@ provenance:
   seeded_at: 2026-03-26T04:41:26.625Z
   seeded_from:
     kind: pull_bundle
-    upstream_record_included: true
+    imported_record_included: true
     site_snapshot_included: true
 status:
   site_status: decidable
   site_badge: DECIDABLE
   repo_status: cataloged
-  upstream_status: decidable
-  upstream_last_update: 2025-08-31
+  imported_status: decidable
+  imported_last_update: 2025-08-31
 cluster: graph-theory
 prize:
   display: $500
@@ -38,5 +38,5 @@ evidence_path: EVIDENCE.md
 formalization_path: FORMALIZATION.md
 formalization:
   status: planned
-  upstream_state: no
-  upstream_last_update: 2025-08-31
+  imported_state: no
+  imported_last_update: 2025-08-31

package/problems/2/AGENT_START.md

@@ -14,4 +14,4 @@ Working assumptions:
 - Harness depth: dossier
 
 First honest move:
-- tighten the local dossier for problem 2 against its pull bundle, references, and upstream provenance before widening claims.
+- tighten the local dossier for problem 2 against its pull bundle, references, and import provenance before widening claims.

package/problems/2/EVIDENCE.md

@@ -1,7 +1,7 @@
 # Evidence
 
 - This dossier was seeded for Erdos Problem #2 from a pull bundle.
-- Upstream record included: yes
+- Imported record included: yes
 - Site snapshot included: yes
 - Repo status at seed time: cataloged
 - Harness depth at seed time: dossier

package/problems/2/FORMALIZATION.md

@@ -1,8 +1,8 @@
 # Formalization
 
 - Local status: planned
-- Upstream formalized state: no
-- Upstream formalized last update: 2025-08-31
+- Imported formalized state: no
+- Imported formalized last update: 2025-08-31
 
 Seed note:
 - this file was created automatically from a pull bundle and should be upgraded as local formal work begins.