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

{lightcone_cli-0.3.3 → 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.3 → lightcone_cli-0.3.5}/claude/lightcone/agents/lc-extractor.md

@@ -2,6 +2,7 @@
 name: lc-extractor
 description: Extract prior insights from scientific papers for ASTRA analyses. Reads PDFs, identifies claims relevant to target decisions, extracts verbatim quotes, and verifies them. Use for literature extraction during /lc-new.
 tools: Read, Bash
+model: sonnet
 ---
 
 You are an ASTRA prior insight extraction agent with self-validation capability. Your task is to extract prior insights from a single paper and format them for an ASTRA analysis. Prior insights are knowledge from literature that informs analysis decisions — they go in the `prior_insights:` section of astra.yaml.

lightcone_cli-0.3.5/claude/lightcone/hooks.json

@@ -0,0 +1,30 @@
+{
+  "SessionStart": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/scripts/activate-venv.sh",
+          "timeout": 5
+        },
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/scripts/session-start.sh",
+          "timeout": 15
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PROJECT_DIR}/.claude/scripts/validate-on-save.sh",
+          "timeout": 15
+        }
+      ]
+    }
+  ]
+}

lightcone_cli-0.3.5/claude/lightcone/scripts/activate-venv.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# SessionStart hook: prepend the project venv to PATH for every Bash command
+# Claude Code spawns this session.
+#
+# We don't `source` activate -- we only need PATH and VIRTUAL_ENV. Sourcing
+# activate also runs prompt mutations and defines a deactivate function we
+# don't want, and any non-zero status under `set -e` would silently skip
+# the writeback (the failure mode behind issue #103). Writing the two
+# exports directly to CLAUDE_ENV_FILE is the documented mechanism and is
+# what every downstream hook implicitly relies on for `astra` / `lc` to
+# resolve to the project venv rather than whatever system install happens
+# to be on PATH.
+
+VENV="$CLAUDE_PROJECT_DIR/.venv"
+[ -d "$VENV/bin" ] || exit 0
+[ -n "$CLAUDE_ENV_FILE" ] || exit 0
+
+{
+    echo "export VIRTUAL_ENV=$VENV"
+    echo "export PATH=$VENV/bin:\$PATH"
+} >> "$CLAUDE_ENV_FILE"
+
+exit 0

lightcone_cli-0.3.5/claude/lightcone/scripts/session-start.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# SessionStart hook: surface a terse project status to the agent.
+#
+# 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')
+
+[ -z "$cwd" ] && exit 0
+cd "$cwd" 2>/dev/null || exit 0
+[ -f "astra.yaml" ] || exit 0
+
+# astra and lc both come from the project venv (prepended to PATH by
+# activate-venv.sh). If neither resolved, the venv setup is broken and
+# there is nothing useful we can report.
+command -v astra &>/dev/null || exit 0
+command -v lc &>/dev/null || exit 0
+
+validation_output=$(astra validate astra.yaml 2>&1)
+validation_ok=$?
+
+status_json=$(lc status --json 2>/dev/null)
+counts=$(echo "$status_json" | jq -r '
+    [.universes[].outputs[].status] as $s |
+    {
+        ok: ($s | map(select(. == "ok")) | length),
+        stale: ($s | map(select(. == "stale")) | length),
+        missing: ($s | map(select(. == "missing")) | length),
+        alias: ($s | map(select(. == "alias")) | length)
+    } | "\(.ok) \(.stale) \(.missing) \(.alias)"
+' 2>/dev/null)
+read -r ok_count stale_count missing_count alias_count <<<"$counts"
+ok_count=${ok_count:-0}
+stale_count=${stale_count:-0}
+missing_count=${missing_count:-0}
+alias_count=${alias_count:-0}
+
+if [ "$validation_ok" -eq 0 ]; then
+    summary="ASTRA project — validation: valid"
+else
+    summary="ASTRA project — validation: has errors"
+fi
+
+summary="$summary
+Materialization: ok=$ok_count stale=$stale_count missing=$missing_count alias=$alias_count
+
+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
+    # ("✓ Schema validation passed" etc.) and the actual error block is
+    # at the bottom.
+    error_preview=$(echo "$validation_output" | tail -20)
+    summary="$summary
+
+Validation errors (run 'astra validate astra.yaml' for full output):
+$error_preview"
+fi
+
+needs_run=$((missing_count + stale_count))
+if [ "$needs_run" -gt 0 ]; then
+    summary="$summary
+
+ACTION REQUIRED: $needs_run output(s) need \`lc run\` ($missing_count missing, $stale_count stale)."
+fi
+
+jq -n --arg ctx "$summary" '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
+exit 0

lightcone_cli-0.3.5/claude/lightcone/scripts/validate-on-save.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# PostToolUse(Write|Edit) hook: re-validate after writes to astra.yaml or a
+# universe file, push errors back to the agent as additionalContext.
+#
+# astra is resolved from the project venv via PATH (prepended at
+# SessionStart by activate-venv.sh). Issue #103 traced back to this hook
+# running an older, globally-installed astra when activate-venv failed
+# silently -- with the venv reliably on PATH that whole code path is
+# unnecessary.
+
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+[ -z "$file_path" ] && exit 0
+
+filename=$(basename "$file_path")
+parent=$(basename "$(dirname "$file_path")")
+
+# Filter to astra.yaml at any depth and universe files (universes/*.yaml)
+if [ "$filename" = "astra.yaml" ]; then
+    project_root=$(dirname "$file_path")
+elif [ "$parent" = "universes" ] && [[ "$filename" == *.yaml ]]; then
+    project_root=$(dirname "$(dirname "$file_path")")
+else
+    exit 0
+fi
+
+command -v astra &>/dev/null || exit 0
+cd "$project_root" 2>/dev/null || exit 0
+
+if [ "$filename" = "astra.yaml" ]; then
+    result=$(astra validate astra.yaml 2>&1)
+else
+    result=$(astra validate "$file_path" 2>&1)
+fi
+exit_code=$?
+
+if [ $exit_code -eq 0 ]; then
+    msg="ASTRA validation passed for $filename"
+else
+    msg=$(printf 'ASTRA validation FAILED for %s:\n%s' "$filename" "$result")
+fi
+
+jq -n --arg ctx "$msg" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $ctx}}'
+exit 0

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.3/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).