lightcone-cli 0.3.4__tar.gz → 0.3.5__tar.gz

{lightcone_cli-0.3.4 → lightcone_cli-0.3.5}/.gitignore

@@ -213,3 +213,12 @@ eval-results
 # UV
 ## lockfile should be versioned for applications but not for libraries
 uv.lock
+
+# wrangler files
+.wrangler
+.dev.vars*
+!.dev.vars.example
+!.env.example
+
+# macOS
+.DS_Store

lightcone_cli-0.3.5/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: lightcone-cli
+Version: 0.3.5
+Summary: Lightcone command-line toolchain
+Author: Lightcone Research
+License: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: astra-tools>=0.2.5
+Requires-Dist: click>=8.0
+Requires-Dist: dask>=2024.1
+Requires-Dist: distributed>=2024.1
+Requires-Dist: jinja2>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: rocrate>=0.11
+Requires-Dist: snakemake-interface-common>=1.14
+Requires-Dist: snakemake-interface-executor-plugins>=9.0
+Requires-Dist: snakemake>=9.0
+Description-Content-Type: text/markdown
+
+# lightcone-cli
+
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Python](https://img.shields.io/pypi/pyversions/lightcone-cli)](https://pypi.org/project/lightcone-cli/)
+[![Tests](https://github.com/LightconeResearch/lightcone-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/LightconeResearch/lightcone-cli/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/lightcone-cli)](https://pypi.org/project/lightcone-cli/)
+
+<!-- [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) -->
+
+**lightcone-cli** (`lc`) is the agentic execution layer for
+[ASTRA](https://astra-spec.org/latest/) (Agentic Schema for Transparent
+Research Analysis). Describe your analysis to an AI agent and `lc` takes
+care of the rest — specification, execution, and provenance.
+
+## Quick Start
+
+```bash
+uv tool install lightcone-cli
+lc init my-analysis
+cd my-analysis
+claude
+```
+
+Then tell the agent what you have to start from — a research question
+(`/lc-new`), existing code (`/lc-from-code`), or a paper to reproduce
+(`/lc-from-paper`).
+
+→ [Full getting-started guide](https://docs.lightconeresearch.org/user/getting-started/)
+
+## Skills
+
+| Skill | What it does |
+|---|---|
+| [`/lc-new`](https://docs.lightconeresearch.org/skills/lc-new/) | Scope a new analysis from a research question into a full `astra.yaml` spec |
+| [`/lc-from-code`](https://docs.lightconeresearch.org/skills/lc-from-code/) | Bring an existing codebase into ASTRA |
+| [`/lc-from-paper`](https://docs.lightconeresearch.org/skills/lc-from-paper/) | Reproduce a published paper end-to-end |
+| [`/lc-feedback`](https://docs.lightconeresearch.org/skills/lc-feedback/) | File a bug report with version and error context auto-collected |
+
+## Capabilities
+
+- **Multiverse analysis** — define methodological decisions with multiple options; `lc` runs your analysis across all defensible paths automatically
+- **Provenance integrity** — every output gets a content-addressed manifest; `lc verify` detects tampering or broken chains
+- **HPC-ready execution** — Snakemake-backed DAG dispatch with SLURM and container support (Docker, Podman, Apptainer) out of the box
+- **Reproducible publishing** — `lc export wrroc` emits a [Workflow Run RO-Crate](https://www.researchobject.org/workflow-run-crate/) bundle ready for Zenodo or WorkflowHub
+
+→ [Full documentation](https://docs.lightconeresearch.org)
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE) for details.

lightcone_cli-0.3.5/README.md

@@ -0,0 +1,50 @@
+# lightcone-cli
+
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Python](https://img.shields.io/pypi/pyversions/lightcone-cli)](https://pypi.org/project/lightcone-cli/)
+[![Tests](https://github.com/LightconeResearch/lightcone-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/LightconeResearch/lightcone-cli/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/lightcone-cli)](https://pypi.org/project/lightcone-cli/)
+
+<!-- [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) -->
+
+**lightcone-cli** (`lc`) is the agentic execution layer for
+[ASTRA](https://astra-spec.org/latest/) (Agentic Schema for Transparent
+Research Analysis). Describe your analysis to an AI agent and `lc` takes
+care of the rest — specification, execution, and provenance.
+
+## Quick Start
+
+```bash
+uv tool install lightcone-cli
+lc init my-analysis
+cd my-analysis
+claude
+```
+
+Then tell the agent what you have to start from — a research question
+(`/lc-new`), existing code (`/lc-from-code`), or a paper to reproduce
+(`/lc-from-paper`).
+
+→ [Full getting-started guide](https://docs.lightconeresearch.org/user/getting-started/)
+
+## Skills
+
+| Skill | What it does |
+|---|---|
+| [`/lc-new`](https://docs.lightconeresearch.org/skills/lc-new/) | Scope a new analysis from a research question into a full `astra.yaml` spec |
+| [`/lc-from-code`](https://docs.lightconeresearch.org/skills/lc-from-code/) | Bring an existing codebase into ASTRA |
+| [`/lc-from-paper`](https://docs.lightconeresearch.org/skills/lc-from-paper/) | Reproduce a published paper end-to-end |
+| [`/lc-feedback`](https://docs.lightconeresearch.org/skills/lc-feedback/) | File a bug report with version and error context auto-collected |
+
+## Capabilities
+
+- **Multiverse analysis** — define methodological decisions with multiple options; `lc` runs your analysis across all defensible paths automatically
+- **Provenance integrity** — every output gets a content-addressed manifest; `lc verify` detects tampering or broken chains
+- **HPC-ready execution** — Snakemake-backed DAG dispatch with SLURM and container support (Docker, Podman, Apptainer) out of the box
+- **Reproducible publishing** — `lc export wrroc` emits a [Workflow Run RO-Crate](https://www.researchobject.org/workflow-run-crate/) bundle ready for Zenodo or WorkflowHub
+
+→ [Full documentation](https://docs.lightconeresearch.org)
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE) for details.

{lightcone_cli-0.3.4 → lightcone_cli-0.3.5}/claude/lightcone/scripts/session-start.sh

@@ -1,11 +1,12 @@
 #!/bin/bash
 # SessionStart hook: surface a terse project status to the agent.
 #
-# Reports validation status, materialization counts, and pointers to the
-# canonical reference docs. Project name / decision count / universe count
-# are intentionally omitted -- they are trivia the agent reads from
-# astra.yaml and CLAUDE.md when needed, and they cost against the 10k
-# additionalContext budget.
+# Reports validation status, materialization counts, and a tight CLI
+# primer so the agent knows what substrate commands exist and which
+# reference skills carry the depth. Project name / decision count /
+# universe count are intentionally omitted -- they are trivia the agent
+# reads from astra.yaml and CLAUDE.md when needed, and they cost against
+# the 10k additionalContext budget.
 
 input=$(cat)
 cwd=$(echo "$input" | jq -r '.cwd // empty')
@@ -48,7 +49,13 @@ fi
 summary="$summary
 Materialization: ok=$ok_count stale=$stale_count missing=$missing_count alias=$alias_count
 
-References: .claude/guides/astra-reference.md (spec) and .claude/guides/lightcone-cli-reference.md (CLI)."
+Substrate CLIs (use --help on any):
+  lc init / lc run / lc status / lc verify / lc build / lc export wrroc
+  astra validate / astra paper add / astra universe generate
+
+Reference skills (invoke when the surface above isn't enough):
+  /astra   — astra.yaml spec: decisions, prior_insights, findings, evidence, sub-analyses, narrative anchors
+  /lc-cli  — lc workflow: spec-code invariant, status interpretation, failure diagnosis"
 
 if [ "$validation_ok" -ne 0 ]; then
     # tail rather than head -- the leading lines are success markers

lightcone_cli-0.3.5/claude/lightcone/skills/README.md

@@ -0,0 +1,43 @@
+# lightcone-cli skills
+
+Each subdirectory is one Claude Code skill: `SKILL.md` plus optional `references/`, `assets/`, and `scripts/`. `lc init` copies these into a project's `.claude/skills/` so they are discoverable to Claude Code sessions.
+
+## Project lifecycle skills
+
+| Skill | Role |
+|---|---|
+| `lc-new` | Scaffold a new ASTRA-shaped project from a research question. |
+| `lc-from-code` | Bring an existing codebase into ASTRA — scan, spec, parameterize. |
+| `lc-from-paper` | Reproduce a published paper in ASTRA (paper-reproduction bundle entry point — see below). |
+| `lc-feedback` | Report bugs and feature requests upstream. |
+| `ralph` | Author a constitution and run a ralph loop against it (authoring + launching + iterating in one skill). `lc-from-paper` uses this for the long middle of a reproduction; standalone for any other long-running work. |
+
+## Reference skills
+
+Not direct entry points — Claude invokes these (or other skills invoke them) to load reference content into the session. The session-start hook primes their names so they're discoverable from turn one.
+
+| Skill | Role |
+|---|---|
+| `astra` | Reference for the `astra.yaml` spec: structure, decisions, options, prior insights, findings, evidence, sub-analyses, narrative anchors, composition mechanics. |
+| `lc-cli` | Reference for `lc` workflow: commands, the Spec-Code Invariant, status interpretation, failure diagnosis, multiverse runs, WRROC export. |
+
+## Paper-reproduction bundle
+
+A self-contained toolkit for reproducing published papers in ASTRA. The bundle is co-located so a single `lc init` brings the full toolkit into a project — no plugin marketplace, no separate installs.
+
+| Skill | Role |
+|---|---|
+| [`lc-from-paper`](lc-from-paper/SKILL.md) | **Reproduction driver.** ORIENT-first; one pre-loop phase in the user's main session that asks for the paper, runs `/paper-extraction` inline, interviews the user (grounded in the paper), clones the reference code and runs `/lc-from-code` scan-only (when a repo exists), and drafts the per-paper `constitution.md` + `CLAUDE.md`. Then hands off to a ralph loop whose iterations carry the long middle: ARCHITECT → SPECIFY → LITERATURE → IMPLEMENT → RUN → COMPARE. When the loop closes (constitution `status: closed` after COMPARE returns `pass`), REVIEW runs back in the user's main session. Fidelity intent — captured as prose at ORIENT — is what every iteration reads when sizing its next move, and what COMPARE grades opportunities against. |
+| [`ralph`](ralph/SKILL.md) | The loop substrate. `lc-from-paper`'s ORIENT invokes `/ralph`'s Authoring mode to draft the per-paper constitution; the loop launcher hands off after ORIENT lands. Each iteration runs `/ralph`'s Loop protocol against the constitution. |
+| [`narrative`](narrative/SKILL.md) | Author the `narrative:` prose and decision `rationale:` in `astra.yaml`. Invoked by `lc-from-paper`'s ARCHITECT (for the structural narrative) and SPECIFY (for anchored content narrative). |
+| [`paper-extraction`](paper-extraction/SKILL.md) | Turn an arXiv ID or DOI into a standardized `work/reference/` directory: structural index (figures, tables, outline, citations with resolved DOIs) plus a stub `astra.yaml` for the paper. Primary acquisition path for `lc-from-paper`'s ORIENT (Stage 2); also invoked per cited paper by LITERATURE. |
+| [`check-sentence-by-sentence`](check-sentence-by-sentence/SKILL.md) | Audit paper claims against code locations (`file:line` or `NOT FOUND`). Invoked from `lc-from-paper`'s REVIEW close-out (opt-in); also user-invokable directly. |
+| [`figure-comparison`](figure-comparison/SKILL.md) | Build a self-contained HTML side-by-side: original figures/tables/numerics vs replicated. Invoked from `lc-from-paper`'s REVIEW close-out (mandatory); also user-invokable directly. |
+
+The full reproduction story spans these skills. `lc-from-paper`'s `SKILL.md` names each by role and tells the agent when to invoke them; the siblings stand alone and don't know about `lc-from-paper`.
+
+### Why bundle (not depend on plugin install)
+
+- **Testability.** We want to verify `lc-from-paper` invokes its sibling skills correctly. That only works when all are in the same checkout.
+- **Single install path.** `lc init` brings the full toolkit. Adding a separate plugin-marketplace step is friction we don't need.
+- **Future consolidation is open.** The long-run shape may be `astra` ships skills in `astra`, `lc` ships skills in `lightcone-cli`, plus a centralized external-skills list. Today: bundle it all. See [[lightcone/skills-location-policy]].

lightcone_cli-0.3.4/claude/lightcone/guides/astra-reference.md → lightcone_cli-0.3.5/claude/lightcone/skills/astra/SKILL.md

@@ -1,3 +1,17 @@
+---
+name: astra
+description: >
+  Comprehensive reference for the `astra.yaml` specification — top-level
+  structure, sub-analyses, inputs/outputs, decisions and options, prior
+  insights and findings, evidence and quote verification, narrative
+  anchors, and composition mechanics. Invoke whenever reading, writing,
+  validating, or debugging an `astra.yaml` spec; whenever working with
+  decisions, options, prior_insights, findings, or evidence; or whenever
+  the user asks about ASTRA schema, spec syntax, or sub-analysis
+  composition.
+allowed-tools: Read, Glob, Grep, Bash(astra:*)
+---
+
 # ASTRA Reference
 
 ## What an ASTRA Analysis Is
@@ -100,6 +114,17 @@ A decision is a methodological choice where a different defensible option could
 
 Decisions may carry an optional `tags:` list for grouping (e.g. `[preprocessing]`, `[physics]`, `[stats]`). Keep the tag vocabulary **small and consolidated** -- reuse existing tags rather than minting new ones, since tags are mostly useful for cross-cutting views over a shared decision space, and that view fragments quickly when every decision invents its own label.
 
+### Options
+
+Each decision must have at least one option. Options are `key: { ... }` entries:
+
+- `label:` (required) -- short human-readable name for compact rendering.
+- `description:` (optional) -- longer prose explaining what the option means.
+- `insights:` (optional) -- list of `prior_insights:` IDs that justify this option; back-references the supporting evidence (see [Prior Insights and Findings](#prior-insights-and-findings)).
+- `excluded:` + `excluded_reason:` -- option considered but rejected. See [Constraints](#constraints).
+
+`label:` and `options:` are required on the decision itself. An aliased decision (one that points at another via `from: ../decisions.foo` -- see [Composition Mechanics](#composition-mechanics)) inherits both from its source and doesn't redeclare them.
+
 ### Parameterization
 
 **Every decision must be parameterized in code** -- never hardcode a decision value. The recipe's `command:` template references it via `{decisions.<id>}` (see [Command Template Substitution](#command-template-substitution)).
@@ -137,6 +162,8 @@ Set `container:` at analysis level (all recipes inherit); per-recipe `container:
 
 Runners expand `{...}` placeholders in `command:` before invoking it: `{inputs.<id>}` (input path), `{inputs}` (all input paths, declared order), `{decisions.<id>}` (active option ID), `{output}` (artifact path), `{{`/`}}` (literal braces). Every `{inputs.<id>}` and `{decisions.<id>}` must name something declared in the parent Output's `inputs:`/`decisions:` lists -- always **local IDs** (no `../`; bridging is declared once at the Input/Decision via `from:`).
 
+Text outside `{...}` is literal command text and isn't validated. Static constants (`--max-iter 1000`), per-output specialisations when fan-out is unrolled into one Output per value (`--tracer lrg1`), and shell features (`${VAR}`, pipes, redirects) all live as plain text. Only values that vary across the multiverse need to be `{decisions.<id>}` placeholders -- there is no separate `params` channel, and Snakemake-style wildcards (`{chunk_id}`, `{block_i}`) have no spec-level analogue: either inline the value, unroll the fan-out into one Output per value, or describe only the aggregated artifact.
+
 ### Conditional Outputs
 
 Outputs can have `when` conditions -- the output only exists when the condition is met for a given universe. Uses the same syntax as decision `when` (negation with `~`, lists AND'd).
@@ -171,7 +198,7 @@ Two kinds of insight, distinguished by direction:
 - **Prior insights** (`prior_insights:`) — knowledge from outside the analysis that informs decisions. From literature (by DOI) or artifacts from a prior/parent analysis.
 - **Findings** (`findings:`) — conclusions from the analysis itself, backed by its own output artifacts.
 
-Both use the same Insight model: `id`, `label` (optional), `claim`, `created_at`, `evidence`, plus optional `derived` (true if synthesized/inferred from multiple sources), `scope` (applicability conditions), `tags`, `notes`. Placement determines direction.
+Both use the same Insight model. Required: `id`, `claim`, `created_at` (ISO 8601 datetime — e.g. `"2025-02-01T14:00:00"`), `evidence`. Optional: `label`, `derived` (true if synthesized/inferred from multiple sources), `scope` (applicability conditions), `tags`, `notes`. Placement determines direction.
 
 Each evidence item has its own fields: `id`, exactly one of `doi` (literature) or `artifact` (output ID), and either a `quote` (TextQuoteSelector with required `exact`, optional `prefix`/`suffix`) or `location` (FragmentSelector with `value` like `"page=6"` and/or 1-indexed `page`). DOI evidence may add `version` (arXiv version). Artifact evidence may add `snapshot` (path to an immutable artifact copy) and `source_commit` (git commit that produced it).
 

lightcone_cli-0.3.5/claude/lightcone/skills/check-sentence-by-sentence/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: check-sentence-by-sentence
+description: >
+  Sentence-by-sentence audit of a paper against an ASTRA project's code. For
+  every claim about implementation or results in the methodology, results,
+  discussion, and appendices, locate the corresponding code (file:line) or
+  mark NOT FOUND. Only the user can invoke this skill, though this skill can be suggested for the user to invoke during paper reproduction. Other skills may mention this skill as an optional follow-up, but should not invoke it themselves. Run from the project folder containing astra.yaml. In lc-from-paper projects, read paper sources from
+  work/reference/: prefer arXiv TeX under work/reference/source/, fall back to
+  Docling/Pandoc markdown at work/reference/document.md.
+argument-hint: "[path to paper source, e.g. work/reference/source/main.tex or work/reference/document.md]"
+---
+
+# /check-sentence-by-sentence
+
+Audit a paper against the code in this ASTRA project, sentence by sentence.
+Every sentence that asserts an implementation detail or a numerical/empirical
+result is located in the code (`file:line`) or marked NOT FOUND. The agent
+does NOT run any code -- this is a static reading audit.
+
+In lc-from-paper projects, the paper substrate comes from `work/reference/`.
+Path A is arXiv source at `work/reference/source/`; Path B is the parsed
+markdown fallback at `work/reference/document.md`, produced by Docling or
+Pandoc.
+
+## Setup
+
+1. **Confirm project root.** Read `astra.yaml` in the current working
+   directory. If it is missing, ask the user:
+
+   > "I do not see an `astra.yaml` in the current directory. Please point me
+   > to the ASTRA project folder, or `cd` there and re-invoke."
+
+   Stop until resolved.
+
+2. **Confirm paper source.** The user may have passed a path as an
+   argument. Resolve it in this order:
+
+   1. If the argument is a `.tex` file, use it in `tex` mode.
+   2. If the argument is `work/reference/` or another directory, first look
+      for TeX source under `<dir>/source/`, then for `<dir>/document.md`.
+   3. If no argument was supplied, prefer the lc-from-paper layout:
+      - `work/reference/source/<main>.tex` if TeX source exists. Identify the
+        main file with `grep -l '\\documentclass' work/reference/source/*.tex`;
+        if exactly one file matches, use it. If multiple files match, ask the
+        user which one is the main paper file. After identifying the main
+        file, expand its local `\input{...}` and `\include{...}` files before
+        section enumeration; many arXiv papers keep most prose outside the
+        main TeX wrapper.
+      - `work/reference/document.md` if there is no TeX source. This is the
+        Docling/Pandoc fallback and should be audited in `markdown` mode.
+   4. Only after those lc-from-paper paths fail, look for an obvious legacy
+      `.tex` source in cwd: a top-level `*.tex`, or one inside `paper/`,
+      `tex/`, or a similarly named subdirectory. If exactly one obvious
+      candidate is found, use it in `tex` mode.
+
+   If no usable source is found, ask:
+
+   > "Which paper source should I audit? Please give me a `.tex` path or
+   > `work/reference/document.md`."
+
+   If only `work/reference/paper.pdf` exists, ask the user to run the PARSE
+   phase first so `work/reference/document.md` exists. Do not audit PDFs
+   directly.
+
+## Section enumeration
+
+This is **your job in the main agent** -- do it carefully so each subagent
+gets a precise line range. Do NOT read full section content; only enough to
+identify boundaries.
+
+1. Enumerate sections according to source mode:
+   - In `tex` mode, first build the ordered audit source list. Start with the
+     main TeX file, scan it for local `\input{...}` and `\include{...}` paths,
+     normalize missing `.tex` suffixes, and include those files when they
+     exist under the same source tree. Recurse one level deeper when an
+     included file itself includes local TeX files. Ignore package/style
+     imports (`\usepackage`, `.sty`, `.cls`) and remote/generated files. If
+     the main file is mostly a wrapper, the leaf included files will carry
+     most audit units.
+   - For every file in the TeX audit source list, use `grep -n` for
+     `^\\section`, `^\\subsection`, and `^\\appendix`. Record each match's
+     file path, line number, and label.
+   - In `markdown` mode, use `grep -n` for markdown headings
+     (`^#`, `^##`, `^###`, etc.) in `work/reference/document.md`. Treat
+     heading depth the way TeX treats section/subsection. If Docling emitted
+     unnumbered headings, use their text labels.
+2. Get the file's total line count with `wc -l`.
+3. Compute each section's line range: **start = the section's own line
+   number; end = (next section/subsection or same/lower heading-depth start
+   minus 1 in the same source file), or that source file's last line for the
+   final section in that file.** For a section that contains subsections,
+   each subsection's range runs from its own line to (next subsection
+   start − 1), and the section's pre-subsection prose (if any) becomes its
+   own audit unit covering (section line + 1) to (first subsection − 1) if
+   that span is non-trivial.
+4. Mark sections appearing after `\appendix` (TeX) or after an `Appendix` /
+   `Appendices` heading (markdown) as appendices regardless of label.
+
+Identify the audit-relevant sections:
+
+- Methodology (often `Methods`, `Analysis`, `Data`, `Sample selection`)
+- Results
+- Discussion (often `Discussion and Conclusions`)
+- Appendices (every section after `\appendix`)
+
+Skip Abstract, Introduction, Acknowledgements, References, author lists.
+
+For each retained section, check whether it has subsections. **Spin up one
+subagent per leaf (sub)section** -- a section with subsections becomes one
+subagent per subsection (plus optionally one for any pre-subsection prose
+span); a section without subsections becomes one subagent for the whole
+section. Spawn them all in a single message so they run in parallel.
+
+## Subagent prompt
+
+Use `Agent(subagent_type="general-purpose", ...)`. Pass each subagent:
+
+- The absolute path to the paper source file for this section
+- The paper source mode: `tex` or `markdown`
+- The exact section/subsection label and the line range in the source file
+  it covers (so it knows where to read)
+- The absolute path to the project root (which contains `astra.yaml`)
+- The instructions below, verbatim
+
+```
+You are auditing one (sub)section of a paper against an ASTRA project's
+code. Your job is mechanical and exhaustive.
+
+INPUTS
+- Paper source file: <path>
+- Source mode: <tex|markdown>
+- Section: <name>, lines <start>-<end>
+- Project root: <path>
+
+PROCEDURE
+1. Read the assigned section of the paper. Split it into sentences using
+   common sense, not naive period-splitting. In `tex` mode, use TeX-aware
+   splitting; in `markdown` mode, preserve Docling/Pandoc math blocks,
+   captions, and headings as source text. Treat `e.g.`, `i.e.`, `et al.`,
+   `Fig.`, `Eq.`, `Sec.`, `Dr.`, decimals (`0.5`), inline math `$...$`,
+   and citation commands (`\citep{...}`, `\citet{...}`) as part of the
+   surrounding sentence, not boundaries. Display equations belong to
+   whichever sentence introduces them.
+2. For each sentence, decide using common sense: does it make a concrete
+   claim about an IMPLEMENTATION DETAIL (a method, parameter, threshold,
+   formula, data cut, model choice, sample definition, algorithmic step)
+   or a RESULTS DETAIL (a numerical value, plot, fitted parameter,
+   statistical outcome)? If neither -- pure motivation, citation prose,
+   or generic framing -- skip it.
+3. Before searching, **read `astra.yaml` once** -- it is a pre-built
+   paper↔code map maintained by the project. Harvest specifically:
+     - `narrative.methods` — links paper methodology concepts to decision
+       IDs (e.g. paper prose "the chosen <method>" → `#decisions.<id>`)
+     - `narrative.findings` — links paper claims/values to result anchors
+     - `prior_insights` (if present) — extracted paper quotes already tied
+       to decisions
+     - per-decision `evidence` quotes and `description` fields
+   Treat these as your translation table: paper prose → decision/output
+   IDs → script files. Do not re-derive what the spec already encodes.
+
+   For everything not covered by the spec, use common sense to translate
+   concepts. In general:
+     - A quality cut stated as a ratio or threshold may appear in code
+       under an inverted form or a different variable name -- map by
+       meaning, not by symbol.
+     - A named model or distribution will usually appear as a function
+       whose name describes its shape or role, not as the paper's prose
+       phrasing.
+     - A cited constant from a referenced paper will usually appear as a
+       module-level constant or as an option value in a decision.
+   Grep for the underlying concept, not just the paper's wording.
+4. For every claim-bearing sentence, search the project code (`scripts/`,
+   source files, `universes/`, `astra.yaml`, `results/`) for where the
+   claim is implemented or computed. Use Grep, Glob, and Read.
+5. Record one of:
+   - (quote, path/file.py:LINE, optional <10-word note)
+     when the sentence's claim is implemented or computed at that location
+   - (quote, NOT FOUND, optional <10-word note)
+     when no implementation or matching computation is present
+
+CONSTRAINTS
+- Do NOT run any code. No Bash beyond ls/grep/find/wc for searching.
+- Do NOT read the paper outside the assigned line range.
+- Quote the sentence verbatim, trimmed to a single sentence. If the
+  sentence is long, you may include just the claim-bearing clause but
+  preserve enough text to identify it.
+- file:line should point to the most specific line that implements or
+  states the claim (the function call, parameter assignment, or computed
+  value -- not just the file).
+- Notes must be under 10 words. Use them for nuance like "approximate
+  match", "different constant", "implemented but commented out",
+  "value computed at runtime, not statically comparable", "produced as
+  figure but printed value not stored".
+- For numerical results that the paper states as a final number, point
+  at the line that computes the value and use a note like "value
+  computed at runtime" -- you cannot verify numerical agreement without
+  executing code, and that is fine.
+
+OUTPUT
+Return a JSON-ish list, one entry per sentence, in paper order:
+
+[
+  {"quote": "...", "location": "scripts/foo.py:142", "note": "..."},
+  {"quote": "...", "location": "NOT FOUND", "note": "..."},
+  ...
+]
+
+Return nothing else.
+```
+
+## Aggregation
+
+When all subagents return, you receive raw entries from every claim-bearing
+sentence each subagent kept. **Do not just concatenate and print them.**
+Two filtering passes happen here, in this order:
+
+### Pass 1 — drop non-computational sentences
+
+Subagents are deliberately generous about what they keep, so the raw list
+contains a long tail of sentences that quote the paper but do not actually
+correspond to anything you would expect to find in code. **Drop any entry
+whose sentence is:**
+
+- **Framing / motivation** — sentences whose job is to set up the next
+  step, e.g. "the first step is...", "to investigate this...", "we want
+  to look at...", "for this reason..."
+- **Citation prose / literature comparison** — sentences that compare to
+  or quote prior literature, e.g. "agrees with values typical of previous
+  measurements...", "much like Author+YYYY they show...", "in particular,
+  Author found <value>..."
+- **Theoretical framing or derivations** — sentences asserting a property
+  expected from theory rather than implemented in code, and restatements
+  of textbook identities used only to introduce the next equation
+- **Rhetorical / interpretive claims** — qualitative readings of a
+  figure or trend, e.g. "the trend clearly has an oscillatory
+  behaviour", "the trend seems to be independent of <variable>", "this
+  supports that..."
+- **Conclusions / justifications / qualitative observations** —
+  "thus we conclude that...", "we choose not to include this
+  because...", "by and large the trends are similar"
+- **Future work / speculation** — "this could be improved by...", "the
+  discrepancy could be explained by..."
+- **Forward/backward references with no claim** — "we discuss this in
+  Sec X below", "as described in Sec Y above"
+- **NOT FOUND entries that fall in any of the above categories** — most
+  framing/motivation sentences will land as NOT FOUND because there is
+  nothing to find. Drop them silently; they are noise, not gaps.
+
+Keep an entry only if it asserts something a reader would expect to be
+implemented or computed: a parameter value, a cut, a formula, an
+algorithmic step, a fitted/measured value, a figure that the project
+should produce, a sample size after a specific cut.
+
+When in doubt about a NOT FOUND, ask: "if this sentence is not in the
+code, is that a real gap?" If no, drop it.
+
+### Pass 2 — deduplicate / merge near-duplicates
+
+Subagents do not see each other, and the same claim is often restated
+across sentences within a (sub)section -- e.g. a prose statement of a
+cut followed by a sentence asserting "this is the only cut we make", or
+two sub-equations of one larger formula that map to the same line.
+Collapse these:
+
+- If two adjacent sentences make the same claim and resolve to the same
+  `file:line`, keep one entry whose quote is the more specific or
+  formula-bearing of the two, and append the other in a short
+  parenthetical only if it adds information.
+- If a paper-text claim and an explicit equation/quoted code map to the
+  same line, prefer the equation/quoted-code form.
+- Do not merge across (sub)sections.
+- Do not merge if the two sentences resolve to different `file:line`
+  locations -- they may look similar but are doing different things.
+
+### Pass 3 — render
+
+After filtering and deduplication, present the result to the user as
+markdown, organized by section -> subsection -> sentence, in paper order:
+
+```
+# Sentence-by-sentence reproduction audit
+
+Paper: <path>
+Project: <path>
+
+## <Section>
+
+### <Subsection>            (omit if no subsections)
+
+- "<sentence quote>"
+  → ✅ `scripts/foo.py:142` -- <note if any>
+
+- "<sentence quote>"
+  → ❌ NOT FOUND -- <note if any>
+- ...
+```
+
+Use `→ ✅ \`file:line\`` for found entries and `→ ❌ NOT FOUND` for
+missing ones. Notes are optional; only include the trailing `-- <note>`
+when the subagent supplied one.
+
+End with a one-line summary:
+
+> N sentences audited across M sections. K implemented, J not found.
+
+### Follow-up suggestion (conditional)
+
+After the summary, scan the NOT FOUND entries and **cluster them**. A
+cluster is a group of NOT FOUND sentences that all relate to the same
+missing piece of work (a missing analysis, a missing diagnostic, an
+unimplemented model variant) -- usually a few consecutive sentences in
+one (sub)section, or sentences that all reference the same concept across
+sections.
+
+**Only emit the follow-up block if there is at least one major
+unimplemented cluster** -- a cluster of genuine missing computation
+substantial enough to be worth offering to add (rule of thumb: ≥3
+sentences of related missing-computation claims, or a single
+heavyweight missing artifact like an entire missing analysis or
+figure). If every NOT FOUND is isolated framing, motivation, or
+qualitative interpretation -- or if the only clusters are tiny -- stop
+after the one-line summary. Do not pad with a follow-up just to have
+one.
+
+When the threshold is met, write a short follow-up block in this shape:
+
+> Major unimplemented clusters: (1) `<short description of cluster 1>`
+> (`<§section>`, ~`<N>` sentences), and (2) `<short description of
+> cluster 2>` (`<§section>`, ~`<N>` sentences). The rest of the NOT
+> FOUND entries are pure framing/motivation/qualitative interpretation,
+> not computational claims. Worth considering as a follow-up if you
+> want full coverage — want me to add `<concrete artifact 1>` and
+> `<concrete artifact 2>`?
+
+Rules for this block:
+- Only call out clusters that look like genuine missing computation, not
+  rhetoric.
+- Keep it to 1–3 clusters. Do not enumerate every NOT FOUND entry.
+- The closing offer must name **concrete artifacts** the user could add
+  (a new output ID, a new script filename, a new decision option, a new
+  figure) -- not vague promises like "fill in the gaps".
+- Cite the section reference in the project's own notation (`§2.1`,
+  `Appendix B`, etc.) and an approximate sentence count.
+- One short paragraph; do not pad.
+
+## Restrictions
+
+- You MUST NOT run project code, recipes, or `lc run`. This is static.
+- You MUST NOT read the paper source wholesale into the main context;
+  delegate to subagents.
+- You MUST NOT modify any project file. Read-only.
+- You MUST NOT fabricate `file:line` locations -- if a subagent's location
+  looks suspicious, ask it to re-verify rather than guessing.
+- You MUST spawn one subagent per leaf (sub)section, in parallel.
+
+## Anti-patterns
+
+- **Auditing intro/abstract** -- skip narrative-only sections; only
+  methodology, results, discussion, and appendices.
+- **Bundling sentences** -- one entry per sentence. Do not collapse
+  multiple claims into one row even if they share a citation or location.
+- **Vague locations** -- a bare filename (`scripts/foo.py`) is not
+  enough; a line number is required for found entries.
+- **Long notes** -- the 10-word cap is a hard limit; reserve notes for
+  signal, not commentary.
+- **Running code to verify** -- this skill is a reading audit. If a claim
+  cannot be verified by reading code alone, mark it found at the
+  computing line and note "value computed at runtime" rather than
+  executing anything.