feat: add branch-driven discovery and archive runner v2 (#5)

* feat: add branch-driven archive runner v2

* docs: clarify archive runner v2 workflow

Author: DeepMathLLM

README.md

@@ -12,40 +12,92 @@ This project explores mathematical creativity in AI—whether it can move beyond
 
 ## Mathematical Object Origin Archive Runner
 
-This runner supports the first research direction by generating and verifying origin archives for mathematical concepts and objects. It processes an ordered collection serially, gives each object its own Moonshine project and session, and writes the final Markdown archive only after verification passes.
+This runner supports the first research direction by creating verified origin archives for mathematical concepts, objects, and methods. Each archive focuses on the mathematical problem that motivated the object, the difficulty that had to be overcome, the ideas that led to its formation, and the essential role of its defining structure.
 
-## Moonshine dependency
+Objects are processed serially. Each object receives its own Moonshine project and session, and the final Markdown archive is published only after verification passes.
+
+## What Changed in v2
+
+The original runner accepted a predefined JSON queue. Version 2 retains that workflow and adds branch-driven archive discovery.
+
+- Select objects directly from supplied mathematical branches; no object list is required in advance.
+- Choose objects that arose in response to a concrete mathematical problem or a well-defined problem class.
+- Select, write, and verify one object within one Moonshine task.
+- Continue until the requested number of verified archives has been published.
+- Pass previously attempted object names into later tasks to reduce repetition.
+- Record failed attempts without counting them toward the requested total.
+- Resume interrupted projects and sessions from persistent runner state.
+- Show normal Moonshine output in the terminal with `--stream-output`.
+- Preserve the predefined JSON queue mode for collections assembled manually.
+
+The archive specification and verification criteria now emphasize precise mathematical context rather than a chronology of people, publications, and dates.
+
+The previous queue-focused implementation is preserved on the [`archive-runner-v1`](https://github.com/DeepMathLLM/Creative-Intelligence/tree/archive-runner-v1) branch.
+
+## Moonshine Dependency
 
 This is a Moonshine runtime extension, not a standalone application. Install, initialize, and configure Moonshine by following the [Moonshine repository](https://github.com/DeepMathLLM/Moonshine/tree/main).
 
-Place this repository directly inside the initialized Moonshine runtime home, not inside the Moonshine source-code package. With the default Moonshine setup, the runtime home is `~/.moonshine`. If Moonshine was initialized with `--home`, use that directory instead.
+Place this repository directly inside the initialized Moonshine runtime home, not inside the Moonshine source-code package:
 
 ```text
 <MOONSHINE_HOME>/
-├── config.yaml
-├── config/
-├── projects/                              # Moonshine projects created for individual objects
-├── sessions/                              # Moonshine session records
-├── skills/
-│   └── installed/                         # Runtime copies installed automatically by the runner
-└── Creative-Intelligence/                 # This GitHub repository
+└── Creative-Intelligence/
     ├── README.md
     ├── run_archive.py
     ├── archive-format-specification.md
     ├── tests/
-    │   └── test_run_archive_offline.py
-    ├── skills/
-    │   ├── math-object-origin-archive/
-    │   │   └── SKILL.md
-    │   └── verify-math-object-origin-archive/
-    │       └── SKILL.md
+    └── skills/
+        ├── math-object-origin-archive/
+        │   └── SKILL.md
+        └── verify-math-object-origin-archive/
+            └── SKILL.md
+```
+
+The runner treats the parent of `Creative-Intelligence` as `MOONSHINE_HOME` and automatically installs its two task-specific skills into that runtime when it starts.
+
+Run all commands from the initialized Moonshine runtime home:
+
+```bash
+cd <MOONSHINE_HOME>
 ```
 
-`config.yaml` and the other runtime directories are created by `python -m moonshine init`. The runner treats its parent directory as `MOONSHINE_HOME` and automatically installs the two included skills into that runtime when it starts.
+## Branch-Driven Discovery
+
+This is the primary v2 workflow. Supply one or more mathematical branches, the number of verified archives to produce, and a stable run name:
+
+```bash
+python Creative-Intelligence/run_archive.py --branches "Differential Geometry" "Algebraic Topology" "Functional Analysis" --target-archives 10 --run-name graduate-math-v2 --stream-output
+```
+
+The runner repeatedly performs one complete object task:
+
+1. Select a distinct object from the supplied branches.
+2. Create its archive according to `archive-format-specification.md`.
+3. Submit the archive to the verification tool.
+4. Publish it only if verification passes.
+
+Only successfully verified archives count toward `--target-archives`. Failed attempts remain in the run state and their names are treated as previously attempted objects.
+
+### Resume a Discovery Run
+
+Run the same command again with the same:
+
+- `--run-name`;
+- branches in the same order;
+- `--target-archives` value.
+
+These values define the identity of the run. Changing them while reusing the same run name is rejected to prevent an interrupted run from being resumed with different inputs.
 
-## Input
+To retry recorded verification failures before discovering additional objects, add:
 
-Create a UTF-8 JSON file containing an ordered list of objects. The JSON file may be stored anywhere:
+```bash
+--retry-failed
+```
+
+## Predefined JSON Queue
+
+Use this mode when the mathematical objects have already been selected or local materials have been collected. Create a UTF-8 JSON file:
 
 ```json
 {
@@ -65,31 +117,21 @@ Create a UTF-8 JSON file containing an ordered list of objects. The JSON file ma
 }
 ```
 
-`materials` is optional and accepts local UTF-8 text or Markdown files. Relative material paths are resolved from the directory containing the input JSON file, not from the repository or runtime home.
-
-## Run
-
-Run commands from the initialized Moonshine runtime home. Replace `<MOONSHINE_HOME>` with the runtime directory used during Moonshine initialization:
-
-```bash
-cd <MOONSHINE_HOME>
-```
-
-This must be the same directory previously passed to `python -m moonshine --home <MOONSHINE_HOME> init`, or the runtime directory created by the default initialization.
+`materials` is optional and accepts local UTF-8 text or Markdown files. Relative paths are resolved from the directory containing the input JSON file. PDF, Word, and other binary files must first be converted to UTF-8 text or Markdown.
 
 Process every object serially:
 
 ```bash
 python Creative-Intelligence/run_archive.py path/to/concepts.json
 ```
 
-Optionally validate the input without starting Moonshine sessions:
+Validate the input without creating runtime state:
 
 ```bash
 python Creative-Intelligence/run_archive.py path/to/concepts.json --validate-only
 ```
 
-Start from a specific 1-based index:
+Start at a specific 1-based index:
 
 ```bash
 python Creative-Intelligence/run_archive.py path/to/concepts.json --start-index 5
@@ -101,23 +143,50 @@ Retry objects previously marked as failed:
 python Creative-Intelligence/run_archive.py path/to/concepts.json --retry-failed
 ```
 
-Optional flags include `--max-turns N` and `--verbose`. Run the same command again to resume the saved Moonshine sessions. After a run has started, keep its input JSON unchanged; use a new, uniquely named JSON file for another queue.
+Useful options include:
+
+- `--max-turns N`: set the maximum repair turns for queued or retried objects;
+- `--verbose`: print Moonshine status events;
+- `--stream-output`: show reasoning, text, tool summaries, and candidate archives in the terminal.
 
-## Generated files
+Run the same command again to resume. After a queue has started, do not modify its JSON file or referenced material files. Use a new JSON filename for a different queue.
 
-The following directories are created automatically when the runner is used and are not part of the initial repository structure:
+## Verification and Publication
 
-- Final archives: `Creative-Intelligence/archives/<input-name>/`
-- Queue state and project/session associations: `Creative-Intelligence/runs/<input-name>.state.json`
+The runner exposes a session-bound verification tool that checks:
 
-## Offline regression tests
+- mathematical correctness;
+- accuracy and specificity of the mathematical context and formation;
+- whether the archive identifies the concrete problem, obstacle, structural mechanism, and resulting change;
+- compliance with the active format specification.
 
-The deterministic runner contracts can be tested from a standalone checkout without an initialized Moonshine runtime, provider credentials, network access, or model calls. The test harness uses only the Python standard library and provides import-time stubs for the narrow Moonshine symbols required to load `run_archive.py`.
+Accepted verifier output is bound to the expected project, session, and archive hash. The runner refuses to publish unverified content or overwrite a different existing archive.
 
-Run from the `Creative-Intelligence` repository root:
+Resumed sessions must also match the expected Moonshine mode, project, and agent identity. Local materials are bound to their resolved paths and SHA-256 hashes, so changed material cannot silently enter an existing run.
+
+## Generated Files
+
+These directories are created by the runner and are not part of the initial repository:
+
+- Final Markdown archives: `Creative-Intelligence/archives/<run-name>/`
+- Run state and project/session associations: `Creative-Intelligence/runs/<run-name>.state.json`
+
+For JSON queue mode, `<run-name>` is derived from the input filename. Moonshine stores the associated projects and sessions in its own runtime directories.
+
+## Tests
+
+Run the deterministic offline regression suite from the repository root:
 
 ```bash
 python -m unittest discover -s tests -p "test_*.py" -v
 ```
 
-These tests cover runner-owned deterministic behavior such as queue validation, immutable queue state, format-placeholder checks, verifier-output integrity, archive overwrite protection, and provider preflight logic. They do **not** simulate Moonshine agent execution, session storage, MCP tools, or real verification-provider behavior; those remain runtime integration concerns.
+These tests require no configured provider, credentials, network access, or live Moonshine session.
+
+The separate integration suite exercises the real Moonshine runtime with deterministic provider substitutes:
+
+```bash
+python -m unittest -v tests.integration_run_archive_moonshine
+```
+
+It covers session persistence, skill and tool registration, material staging, verification-event storage, recovery, identity rejection, and archive publication. It does not evaluate live model quality, live provider availability, or web/MCP behavior.

archive-format-specification.md

@@ -17,7 +17,7 @@
 
 {Content}
 
-### Background
+### Mathematical Context and Formation
 
 {Content}
 
@@ -27,7 +27,7 @@
 
 ## 3. Notes
 
-{Relevant precursors, historical disputes, related objects, or other supplementary information.}
+{Related objects, terminology distinctions, limitations, or other supplementary information.}
 
 ## 4. Sources
 
@@ -38,14 +38,18 @@
 
 ## Writing Instructions
 
-1. Each archive must document exactly one mathematical object.
+1. Each archive must document exactly one mathematical object that arose in response to a concrete mathematical problem or a well-defined class of problems.
 
-2. “Archive Information,” “Core Record,” and “Sources” are required sections. “Notes” is optional.
+2. “Archive Information” and “Core Record” are required sections. “Notes” and “Sources” are optional.
 
-3. The Core Record must contain the three fixed subsections “Precise Description,” “Background,” and “Essential Role.” “Precise Description” states the object accurately in mathematical terms. “Background” explains the setting from which it arose.
+3. The Core Record must contain the three fixed subsections “Precise Description,” “Mathematical Context and Formation,” and “Essential Role.” “Precise Description” states the object accurately in mathematical terms.
 
-4. Cite important historical claims with numbered references such as `[1]` and `[2]`. State uncertainty explicitly when the evidence is limited or disputed.
+4. “Mathematical Context and Formation” presents a clear and coherent account of the concrete mathematical problem, or well-defined class of problems, that motivated the object. It explains where the mathematical difficulty lay, why the available concepts or methods were inadequate, and which ideas or insights led to the object’s formation. These elements must be connected through their mathematical relationships rather than listed as separate facts, while their emphasis and order depend on the object. The archive concerns mathematical meaning and formation, not a historical story.
 
-5. Distinguish mathematical facts, documented historical facts, and interpretive synthesis. Maintain a professional and objective tone.
+5. “Essential Role” explains precisely which part of the motivating problem the object made tractable, which difficulties it overcame, bypassed, or reformulated, and how specific features of its definition or structure did so. It should distinguish this direct contribution from generic importance or later applications, while also explaining any deeper understanding or structural viewpoint the object introduced.
 
-6. Write mathematical symbols and formulas in LaTeX.
+6. If the archive refers to any material, include “Sources” and list that material there. Use numbered citations such as `[1]` and `[2]` consistently.
+
+7. Distinguish established mathematical facts from interpretive synthesis. State uncertainty explicitly when a claim is uncertain or disputed. Maintain a professional and objective tone.
+
+8. Write mathematical symbols and formulas in LaTeX.