@paradigma-inc/flywheel 0.1.16 → 0.1.25

package/skills/flywheel-prove/references/workflow.md

@@ -0,0 +1,193 @@
+# Workflow
+
+## 0. Prerequisite: Local Toolchain Bootstrap
+
+Ensure the host has:
+- `uv`
+- `elan` (Lean toolchain manager)
+
+If `uv` is missing, install it by OS:
+- macOS/Linux:
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+- Windows (PowerShell):
+  ```powershell
+  irm https://astral.sh/uv/install.ps1 | iex
+  ```
+
+If `elan` is missing, install it by OS:
+- macOS/Linux:
+  ```bash
+  curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh -s -- -y
+  ```
+- Windows (PowerShell):
+  ```powershell
+  Invoke-WebRequest -Uri https://raw.githubusercontent.com/leanprover/elan/master/elan-init.ps1 -OutFile elan-init.ps1
+  powershell -ExecutionPolicy Bypass -File .\elan-init.ps1
+  ```
+
+Verify bootstrap before running pipeline commands:
+
+```bash
+uv --version
+elan --version
+lean --version
+lake --version
+```
+
+## 1. Scaffold Pipeline Into Repo
+
+```bash
+python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+```
+
+`<skill-root>` is the directory that contains this skill.
+
+Creates `<repo-root>/theorem_pipeline` with:
+- `workspace/lean_project/` canonical cumulative Lean project
+- `data/runs/` run metadata and proof briefs
+- `logs/` local Lean verification logs
+- `src/tproof/` local CLI orchestration
+
+## 2. Initialize Lean Toolchain
+
+From `theorem_pipeline/`:
+
+```bash
+uv run -m tproof.cli doctor
+uv run -m tproof.cli init --build
+```
+
+Warning: `init --build` can take several minutes the first time (toolchain/dependency download and initial compilation). Subsequent proving runs in the same workspace are usually much faster because those artifacts are cached.
+Operator requirement: Before running `uv run -m tproof.cli init --build`, explicitly notify the human user in-chat about this first-run delay.
+
+Pinned versions:
+- Lean toolchain: `leanprover/lean4:v4.28.0`
+- Mathlib hash: `8f9d9cff6bd728b17a24e163c9402775d9e6a365`
+
+## 2.1 Source Context Normalization (Conditional)
+
+Handle source ingestion based on user-provided input type.
+
+If input is a PDF:
+- Use `pypdf` (not `pdftotext`) and sanitize mojibake with UTF-8-safe output before theorem formalization.
+- Required output A (full cached extraction):
+  - `theorem_pipeline/workspace/contexts/<pdf_stem>.txt`
+  - Example: `paper.pdf -> theorem_pipeline/workspace/contexts/paper.txt`
+- Required output B (theorem-focused excerpt):
+  - `theorem_pipeline/workspace/contexts/<theorem_slug>_source_excerpt.txt`
+  - Example: `proposition2_source_excerpt.txt`
+- Keep both outputs:
+  - full extraction = reusable cache across multiple theorem proofs from the same paper;
+  - excerpt = focused context for the current theorem.
+- Reuse policy:
+  - if the full extraction file already exists and is still valid for the current PDF, reuse it instead of converting the PDF again.
+
+If input is not a PDF (prompt text, local `.txt`/`.md`/`.tex`, or fetched online source):
+- Skip PDF conversion.
+- Use the source as requested by the user.
+- Store a normalized local source artifact under `theorem_pipeline/workspace/contexts/` (for example, `<theorem_slug>_source.txt`).
+- Optionally store a focused excerpt as `<theorem_slug>_source_excerpt.txt` when useful for theorem-specific context.
+
+ASCII rewrites of common symbols are allowed when needed for robust editing/parsing.
+
+## 3. Create a Proof Run
+
+```bash
+uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt
+```
+
+This writes:
+- `data/runs/<run_id>/run.json`
+- `data/runs/<run_id>/run_brief.md`
+- snapshot of the Lean project for traceability
+
+## 4. Required Agent Routing
+
+Use two workers:
+
+1. Proof worker (math-heavy):
+   - profile: deep-thinking reasoning model for complex mathematics
+   - responsibility: theorem proving, decomposition, and difficult Lean proof terms.
+
+2. Ops worker (programming/reporting):
+   - profile: smaller coding-oriented model for implementation and reporting
+   - responsibility: scripts, logs, verification loops, metadata updates, concise run reports.
+
+## 5. Iterate Until Clean Verification
+
+After proof edits:
+
+```bash
+uv run -m tproof.cli reindex
+uv run -m tproof.cli verify
+```
+
+`verify` fails on:
+- `lake build` failures
+- any unresolved `sorry`
+- any `.lean`/`.md` final artifacts found under `workspace/staging/` (forbidden; move to `ProofWorkspace/Final/`)
+
+When done, set run status:
+
+```bash
+uv run -m tproof.cli set-status <run_id> COMPLETE --note "all goals proven and verified"
+```
+
+## 6. Final Artifact Placement and Sidecar Sketch Files (`.md`)
+
+Final theorem artifacts must be written only under:
+- `theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`
+
+Forbidden output location:
+- `workspace/staging/` for any final proof or sketch artifact.
+
+For every finalized Lean proof file, create a sibling Markdown sketch file:
+- Naming convention:
+  - full proof (Lean-safe filename): `ProofWorkspace/Final/<Name>Full.lean`
+  - sketch: `ProofWorkspace/Final/<Name>Sketch.md`
+  - example pair: `ProofWorkspace/Final/Proposition1Full.lean` and `ProofWorkspace/Final/Proposition1Sketch.md`
+- Keep sidecars in the same module directory so paper authors can trace them easily.
+- In sketch files, all mathematics must be written with LaTeX dollar syntax (`$...$` / `$$...$$`).
+- The `Proof Sketch` section must be fluent mathematical prose (paper style), not a numbered recipe.
+
+Recommended sidecar template:
+
+```md
+# <Theorem Name>
+
+## Statement
+Plain-language statement mapped to the Lean theorem name(s).
+
+## Assumptions
+- A1
+- A2
+- ...
+
+## Proof Sketch
+Write a concise, fluent paragraph (or short sequence of paragraphs) as a mathematician would explain the proof to another mathematician in a paper. Emphasize the key reductions and ideas, but avoid low-level proof script details.
+
+Use inline/display LaTeX where needed, for example:
+`By reducing the claim to $X$, applying $Y$, and combining with $Z$, we obtain the target bound $f(x) \le g(x)$ for all $x \in D$.`
+
+## Corollaries (if required)
+- help
+- match
+- upper-bound
+
+## Lean Artifacts
+- File: <path/to/ProofWorkspace/Final/NameFull.lean>
+- Theorems:
+  - <theorem_name_1>
+  - <theorem_name_2>
+```
+
+Compatibility note:
+- The pipeline indexes/checks only `*.lean` files (`reindex`, module discovery, and `sorry` scan), so `.md` sidecars do not affect Lean verification.
+
+## 7. Final Report Status Line
+
+Keep the existing report format, and append one additional final line:
+- `SUCCESS`
+- or `FAIL: <reason>`

package/skills/flywheel-prove/scripts/scaffold_pipeline.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Scaffold a local Lean theorem proving pipeline into a target repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def run(command: list[str], cwd: Path) -> None:
+    proc = subprocess.run(command, cwd=cwd, text=True, check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(f"Command failed ({proc.returncode}): {' '.join(command)}")
+
+
+def scaffold(repo_root: Path, subdir: str, force: bool) -> Path:
+    skill_root = Path(__file__).resolve().parents[1]
+    template_dir = skill_root / "assets" / "pipeline_template"
+    if not template_dir.is_dir():
+        raise FileNotFoundError(f"Missing template directory: {template_dir}")
+
+    target = (repo_root / subdir).resolve()
+    if target.exists():
+        if not force:
+            raise FileExistsError(
+                f"Target already exists: {target}. Pass --force to replace it."
+            )
+        if target == repo_root.resolve():
+            raise RuntimeError("Refusing to delete repo root.")
+        shutil.rmtree(target)
+
+    shutil.copytree(template_dir, target)
+    return target
+
+
+def ensure_uv_available() -> None:
+    proc = subprocess.run(
+        ["uv", "--version"], capture_output=True, text=True, check=False
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            "Missing `uv` on PATH. Install uv first: https://docs.astral.sh/uv/getting-started/installation/"
+        )
+
+
+def setup_env_with_uv(pipeline_dir: Path) -> None:
+    ensure_uv_available()
+    run(["uv", "sync"], cwd=pipeline_dir)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Scaffold local Lean theorem proving pipeline."
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=Path.cwd(),
+        help="Repository root where the pipeline folder will be created.",
+    )
+    parser.add_argument(
+        "--subdir",
+        type=str,
+        default="theorem_pipeline",
+        help="Subdirectory name for the pipeline workspace.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace target directory if it already exists.",
+    )
+    parser.add_argument(
+        "--setup-env",
+        action="store_true",
+        help="Run `uv sync` in the scaffolded pipeline directory.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    repo_root = args.repo_root.resolve()
+    repo_root.mkdir(parents=True, exist_ok=True)
+
+    pipeline_dir = scaffold(repo_root=repo_root, subdir=args.subdir, force=args.force)
+    if args.setup_env:
+        setup_env_with_uv(pipeline_dir)
+
+    print(f"[OK] Scaffolded pipeline at: {pipeline_dir}")
+    print("Next commands:")
+    print(f"  cd {pipeline_dir}")
+    if not args.setup_env:
+        print("  uv sync")
+    print("  uv run -m tproof.cli doctor")
+    print("  uv run -m tproof.cli init --build")
+    print(
+        "  uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt"
+    )
+    print("  uv run -m tproof.cli verify")
+    print("Optional wrappers:")
+    print("  macOS/Linux: ./bin/tproof doctor")
+    print("  Windows cmd: .\\bin\\tproof.cmd doctor")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/flywheel-reproduce/SKILL.md

@@ -57,8 +57,10 @@ Before execution, recover or establish these inputs:
    - Later reproduce passes must read the control node `content` first and continue from that persisted contract rather than from chat memory.
 3. Classify the source.
    - If the input is already a normalized Flywheel graph export, `flywheel_import_subgraph` may be appropriate.
-   - If it is a markdown wiki, README corpus, blog post, or paper, port it explicitly with node and artifact tools before execution.
-   - If it is a claim-bearing paper or benchmark result, split the work into explicit validation branches rather than treating the whole source as one flat note.
+   - Otherwise, route to one source reference in `references/` using the
+     `Source Type Routing` section below.
+   - Complete source decomposition from the selected reference before step 8
+     branch planning or execution.
 4. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
    - Create a new node with `flywheel_stage_node_create` when needed.
@@ -79,11 +81,13 @@ Before execution, recover or establish these inputs:
    - Prioritize the cheapest branches that most reduce uncertainty first.
    - Prefer explicit validation branches such as baseline checks, mechanism or intermediate-signal checks, ablations, efficiency checks, robustness checks, failure analysis, and follow-up analysis branches after results land.
    - If the branch can run through Flywheel execution directly, use `flywheel_launch_execution` and inspect terminal status before commit.
-   - If the branch needs managed compute, use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+
+   - If the branch needs managed compute, use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
    - Release managed compute when a branch is done. Default to releasing only
      known leases. Use `flywheel_compute_release_all` only when the user
      explicitly requests account-wide cleanup.
    - Stop when the core claim is resolved or the budget ceiling is reached.
+
 9. Commit after the node snapshot is coherent with `flywheel_commit_node`.
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
@@ -131,35 +135,38 @@ Canonical contract shape:
 
 The `Source or claim nodes under test` line is the recovery anchor for later validation passes. If multiple claim nodes are in scope, list the governing node ids or slugs explicitly.
 
-## Wiki Porting
+## Source Type Routing
+
+Route every non-normalized source through one reference file before
+graphification and validation planning.
 
-Use this guide when the source material is a markdown wiki, README corpus, or a Karpathy-style LLM wiki that should become Flywheel nodes. In the flywheel-reproduce skill, do this graphification pass before empirical execution starts.
+Routing order:
 
-### Default Mapping
+1. Deterministic routing.
+2. Natural-language routing.
+3. Generic fallback.
 
-- One wiki page or stable concept -> one Flywheel node.
-- The main page markdown -> the node body/readme field (`content`).
-- A short synopsis of the page -> `summary`.
-- Images, PDFs, datasets, notebooks, code snippets, and other supporting files -> node artifacts.
-- Durable structural relationships -> graph edges.
-- Ordinary wiki hyperlinks -> remain markdown links inside the node body.
+Deterministic routing rules:
 
-Do not try to preserve the source wiki as a file-first mirror inside Flywheel. Flywheel is node-first.
+- Local `.pdf` files -> `references/source-paper.md`
+- `arxiv.org/abs/*`, `arxiv.org/pdf/*`, DOI URLs, direct PDF URLs -> `references/source-paper.md`
+- Markdown files, wiki exports, wiki-like repositories -> `references/source-wiki.md`
+- Blog/article domains and long-form article URLs -> `references/source-blog.md`
+- Local notes trees (Obsidian, Logseq, plain markdown note directories) -> `references/source-notes.md`
 
-### What The Model Should Do
+Natural-language routing rule:
 
-Assume the model is expected to perform the port directly unless the user explicitly asks to build a dedicated importer.
+- If deterministic routing is inconclusive, use user intent from prompt/context
+  (for example, "import this paper", "graph this wiki", "convert this blog
+  post", "port these research notes") and pick the matching source reference.
 
-That means:
+Generic fallback rule:
 
-1. Read the source pages and supporting files.
-2. Create or update nodes explicitly.
-3. Write the page body into node `content`.
-4. Publish supporting files as artifacts.
-5. Add only the graph edges that materially help reasoning or navigation.
-6. Split the claim-bearing work into explicit validation branches before execution.
+- If deterministic and natural-language routing are both inconclusive, load
+  `references/source-generic.md`.
 
-Do not wait for a magical bulk-import surface if the available Flywheel primitives are already enough.
+After choosing a source type, load that reference and complete source
+decomposition before entering step 8 validation branch planning.
 
 ## `flywheel_import_subgraph`
 
@@ -210,5 +217,6 @@ Guidelines:
 - Build the graph explicitly with nodes, artifacts, and selected edges.
 - Keep the source material legible in `content`; do not dump everything into artifacts.
 - Keep the flywheel-reproduce skill scoped by cost and decision value, not by exhaustively trying every possible branch.
+- These claim-validation execution rules apply only when $flywheel-reproduce is the active skill.
 
 See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.

package/skills/flywheel-reproduce/evals/evals.json

@@ -2,7 +2,13 @@
   {
     "id": "claim-bearing-paper-with-no-budget-yet",
     "prompt": "Use $flywheel-reproduce to validate the central empirical claims from this paper in Flywheel. I have not given you a max budget yet, but I do want the source structured and the validation plan prepared.",
-    "expected_output": "Graphify the source and plan explicit validation branches, ask once for a hard max budget before any compute acquisition, and avoid empirical execution until the budget is explicit.",
+    "expected_output": "Create a parent paper node under the requested root, decompose the paper into section child nodes, keep section narratives in each child `content`, attach the PDF to the parent node, and stage explicit validation branch plans. Ask once for a hard max budget before any compute acquisition, and do not execute branches until the budget is explicit. Do NOT produce a single `insight` node with the PDF as the only artifact.",
+    "files": []
+  },
+  {
+    "id": "paper-pdf-decomposes-into-section-children",
+    "prompt": "Use $flywheel-reproduce on the paper PDF in the current folder, attach results under an existing root, plan validation branches, and do not launch execution yet.",
+    "expected_output": "Create a parent paper node under the root, add one child node per top-level paper section, place section narratives in child `content`, and attach the PDF artifact on the parent. Plan at least one explicit validation branch and keep execution unlaunched until budget gating is satisfied. Do NOT emit a single `insight` node with only a summary and the PDF artifact.",
     "files": []
   },
   {