lightcone-cli 0.2.0__py3-none-any.whl

lightcone/cli/claude/lightcone/scripts/activate-venv.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Activate Python virtual environment if it exists in the project directory
+# This hook runs at SessionStart to ensure the venv is active for Claude Code
+
+set -e
+
+# Check if we have a project directory
+if [ -z "$CLAUDE_PROJECT_DIR" ]; then
+    exit 0
+fi
+
+# Check for .venv in project directory
+VENV_DIR="$CLAUDE_PROJECT_DIR/.venv"
+if [ ! -d "$VENV_DIR" ]; then
+    exit 0
+fi
+
+# Determine activate script path based on OS
+if [ -f "$VENV_DIR/bin/activate" ]; then
+    ACTIVATE_SCRIPT="$VENV_DIR/bin/activate"
+elif [ -f "$VENV_DIR/Scripts/activate" ]; then
+    ACTIVATE_SCRIPT="$VENV_DIR/Scripts/activate"
+else
+    exit 0
+fi
+
+# Capture environment before activation
+BEFORE_PATH="$PATH"
+BEFORE_VIRTUAL_ENV="${VIRTUAL_ENV:-}"
+
+# Source the activation script
+# shellcheck source=/dev/null
+source "$ACTIVATE_SCRIPT"
+
+# If CLAUDE_ENV_FILE is set, write environment changes to it
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+    # Write PATH update
+    echo "PATH=$PATH" >> "$CLAUDE_ENV_FILE"
+
+    # Write VIRTUAL_ENV
+    echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> "$CLAUDE_ENV_FILE"
+fi
+
+exit 0

lightcone/cli/claude/lightcone/scripts/check-lc-run.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# PostToolUse hook: Warn when agent runs a Python script that has an integrated recipe
+# Triggers on Bash commands matching "python". Uses astra.helpers for correct YAML parsing.
+# Only fires on specific recipe matches — silent otherwise (no Tier 2 noise).
+# Parses --universe from the command to check the targeted universe; falls back to baseline.
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract the command that was run
+command=$(echo "$input" | jq -r '.tool_input.command // empty')
+
+# Exit silently if no command
+if [ -z "$command" ]; then
+    exit 0
+fi
+
+# Quick filter: only care about commands containing "python"
+if ! echo "$command" | grep -qE 'python[23]?\s'; then
+    exit 0
+fi
+
+# Skip lc/astra commands
+if echo "$command" | grep -qE '(lc|astra)\s'; then
+    exit 0
+fi
+
+# Must be in an ASTRA project
+if [ ! -f "astra.yaml" ]; then
+    exit 0
+fi
+
+# Use Python + astra.helpers to extract recipe commands and match against the agent's command.
+# This correctly handles all YAML variants (block, inline, sub-analyses).
+# Outputs a warning message if a match is found, or nothing if no match.
+msg=$(python3 -c "
+import sys, os, re
+
+try:
+    from astra.helpers import load_yaml, get_outputs_with_recipes
+    from lightcone.engine.status import get_output_status
+    from pathlib import Path
+except ImportError:
+    sys.exit(0)
+
+try:
+    data = load_yaml('astra.yaml')
+except Exception:
+    sys.exit(0)
+
+recipes = get_outputs_with_recipes(data)
+if not recipes:
+    sys.exit(0)
+
+# Parse --universe from the agent's command; fall back to baseline
+agent_cmd = sys.argv[1]
+universe = 'baseline'
+m = re.search(r'--universe[= ]\s*(\S+)', agent_cmd)
+if m:
+    universe = m.group(1)
+
+# Get status for the targeted universe
+try:
+    status = get_output_status(Path('.'), universe)
+except Exception:
+    status = {}
+
+if not status:
+    sys.exit(0)
+
+# Check if any recipe output is integrated (pending or materialized) in this universe
+has_integrated = any(
+    status.get(o.get('id', ''), '') in ('pending', 'materialized')
+    for o in recipes
+)
+if not has_integrated:
+    # No integrated recipes in this universe — Write & Debug phase
+    sys.exit(0)
+
+# Build map: normalized script path -> (output_id, status)
+recipe_scripts = {}
+for o in recipes:
+    cmd = o.get('recipe', {}).get('command', '')
+    out_id = o.get('id', '')
+    out_status = status.get(out_id, 'no_recipe')
+    if out_status not in ('pending', 'materialized'):
+        continue
+    # Extract .py path from recipe command
+    for part in cmd.split():
+        if part.endswith('.py'):
+            normalized = part.lstrip('./')
+            recipe_scripts[normalized] = (out_id, out_status)
+            recipe_scripts[os.path.basename(normalized)] = (out_id, out_status)
+            break
+
+if not recipe_scripts:
+    sys.exit(0)
+
+# Check the agent's command against recipe scripts
+# Split on && || ; to handle chained commands
+subcmds = re.split(r'&&|\|\||;', agent_cmd)
+
+for subcmd in subcmds:
+    subcmd = subcmd.strip()
+    # Extract .py path from this sub-command
+    for token in subcmd.split():
+        if token.endswith('.py'):
+            agent_script = token.lstrip('./')
+            match = recipe_scripts.get(agent_script) or recipe_scripts.get(os.path.basename(agent_script))
+            if match:
+                out_id, out_status = match
+                if out_status == 'pending':
+                    print(f'WARNING: You just ran the script for output \`{out_id}\` (status: pending in {universe}), which has an integrated recipe. Use \`lc run {out_id} --universe {universe}\` instead to ensure reproducibility.')
+                elif out_status == 'materialized':
+                    print(f'NOTE: Output \`{out_id}\` already has results in {universe} from \`lc run\`. If regenerating, use \`lc run {out_id} --universe {universe}\` to keep results reproducible.')
+                sys.exit(0)
+            break
+    # Also handle python -m
+    parts = subcmd.split()
+    for i, p in enumerate(parts):
+        if p == '-m' and i + 1 < len(parts):
+            module_path = parts[i + 1].replace('.', '/') + '.py'
+            match = recipe_scripts.get(module_path) or recipe_scripts.get(os.path.basename(module_path))
+            if match:
+                out_id, out_status = match
+                if out_status == 'pending':
+                    print(f'WARNING: You just ran the module for output \`{out_id}\` (status: pending in {universe}), which has an integrated recipe. Use \`lc run {out_id} --universe {universe}\` instead.')
+                elif out_status == 'materialized':
+                    print(f'NOTE: Output \`{out_id}\` already has results in {universe} from \`lc run\`. If regenerating, use \`lc run {out_id} --universe {universe}\`.')
+                sys.exit(0)
+            break
+" "$command" 2>/dev/null)
+
+# If Python produced a message, return it as hook context
+if [ -n "$msg" ]; then
+    escaped_msg=$(echo "$msg" | jq -Rs .)
+    echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PostToolUse\", \"additionalContext\": $escaped_msg}}"
+fi
+
+exit 0

lightcone/cli/claude/lightcone/scripts/session-start.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+# SessionStart hook: Show ASTRA analysis summary when entering a project
+# Provides context about the current analysis state
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Get the current working directory
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+
+if [ -z "$cwd" ]; then
+    exit 0
+fi
+
+cd "$cwd" 2>/dev/null || exit 0
+
+# Check for active lc-build loop (crash recovery)
+if [ -f ".claude/ralph-loop.local.md" ]; then
+    loop_iter=$(grep '^iteration:' .claude/ralph-loop.local.md 2>/dev/null | awk '{print $2}')
+    loop_max=$(grep '^max_iterations:' .claude/ralph-loop.local.md 2>/dev/null | awk '{print $2}')
+    loop_session=$(grep '^session_id:' .claude/ralph-loop.local.md 2>/dev/null | awk '{print $2}')
+    # Read universe from dedicated frontmatter field (falls back gracefully for old state files)
+    loop_universe=$(grep '^universe:' .claude/ralph-loop.local.md 2>/dev/null | awk '{print $2}')
+    loop_universe="${loop_universe:-unknown}"
+
+    current_session="${CLAUDE_CODE_SESSION_ID:-}"
+
+    # If the loop belongs to a different active session, show informational message only.
+    # This prevents a concurrent session from accidentally resuming or cancelling another session's loop.
+    if [ -n "$loop_session" ] && [ -n "$current_session" ] && [ "$loop_session" != "$current_session" ]; then
+        loop_info="lc-build loop active in another session (universe: ${loop_universe}, iteration ${loop_iter:-?}/${loop_max:-?}). This session is unaffected — manage the loop from its original session."
+        escaped_info=$(echo "$loop_info" | jq -Rs .)
+        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": $escaped_info}}"
+    else
+        loop_warning="Active lc-build loop detected (universe: ${loop_universe}, iteration ${loop_iter:-?}/${loop_max:-?})
+  Resume: /lc-build --universe ${loop_universe}    Cancel: /cancel-ralph"
+        escaped_warning=$(echo "$loop_warning" | jq -Rs .)
+        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": $escaped_warning}}"
+    fi
+    exit 0
+fi
+
+# Sync extraction model from ~/.lightcone/config.yaml to .claude/agents/lc-extractor.md
+if [ -f ".claude/agents/lc-extractor.md" ] && [ -f "$HOME/.lightcone/config.yaml" ]; then
+    ext_model=$(grep '^extraction_model:' "$HOME/.lightcone/config.yaml" 2>/dev/null | awk '{print $2}' | tr -d "'\"")
+    # Default to sonnet if not configured
+    [ -z "$ext_model" ] && ext_model="sonnet"
+    if [ -n "$ext_model" ]; then
+        if ! grep -q "^model:" .claude/agents/lc-extractor.md 2>/dev/null; then
+            # Insert model field after description line
+            sed -i.bak '/^tools:/i\
+model: '"$ext_model" .claude/agents/lc-extractor.md 2>/dev/null && rm -f .claude/agents/lc-extractor.md.bak
+        else
+            # Update existing model field
+            sed -i.bak 's/^model: .*/model: '"$ext_model"'/' .claude/agents/lc-extractor.md 2>/dev/null && rm -f .claude/agents/lc-extractor.md.bak
+        fi
+    else
+        # Empty model = inherit, remove model line if present
+        sed -i.bak '/^model: /d' .claude/agents/lc-extractor.md 2>/dev/null && rm -f .claude/agents/lc-extractor.md.bak
+    fi
+fi
+
+# Check if this is an ASTRA project (has astra.yaml)
+if [ ! -f "astra.yaml" ]; then
+    exit 0
+fi
+
+# Check if astra command is available
+if ! command -v astra &> /dev/null; then
+    # Provide minimal info without CLI
+    echo "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"This is an ASTRA project. The astra CLI is not installed - run 'pip install astra' to enable validation and other commands.\"}}"
+    exit 0
+fi
+
+# Gather analysis information
+analysis_name=$(grep -m1 "^  name:" astra.yaml 2>/dev/null | sed 's/.*name: *"\?\([^"]*\)"\?/\1/' | tr -d '"')
+
+# Count decisions
+decision_count=$(grep -c "^  [a-z_]*:$" astra.yaml 2>/dev/null | head -1)
+# More accurate: count keys under 'decisions:'
+decision_count=$(awk '/^decisions:/{found=1; next} found && /^  [a-z_]+:/{count++} found && /^[a-z]/{exit} END{print count}' astra.yaml 2>/dev/null)
+
+# Count universes
+universe_count=$(ls -1 universes/*.yaml 2>/dev/null | wc -l | tr -d ' ')
+
+# Check validation status
+validation_result=$(astra validate astra.yaml 2>&1)
+if [ $? -eq 0 ]; then
+    validation_status="valid"
+else
+    validation_status="has errors"
+fi
+
+# Build summary
+summary="ASTRA Project: ${analysis_name:-unnamed}
+- Decisions: ${decision_count:-0}
+- Universes: ${universe_count:-0}
+- Validation: ${validation_status}
+- Reference: For astra.yaml syntax and spec format, read .claude/guides/astra-reference.md; for CLI and execution, read .claude/guides/lightcone-cli-reference.md"
+
+# If validation failed, add error summary
+if [ "$validation_status" = "has errors" ]; then
+    # Get first few lines of errors
+    error_preview=$(echo "$validation_result" | head -5)
+    summary="$summary
+
+Validation errors (run 'astra validate astra.yaml' for details):
+$error_preview"
+fi
+
+# Add lc status if lc CLI is available
+if command -v lc &> /dev/null; then
+    lc_status=$(lc status 2>&1)
+    lc_exit=$?
+    if [ $lc_exit -eq 0 ]; then
+        # Count outputs in each state
+        pending_count=$(echo "$lc_status" | grep -c "pending")
+        ok_count=$(echo "$lc_status" | grep -c "ok")
+        no_recipe_count=$(echo "$lc_status" | grep -c "no recipe")
+
+        summary="$summary
+
+Materialization status:
+- ok: ${ok_count}
+- pending: ${pending_count}
+- no recipe: ${no_recipe_count}"
+
+        if [ "$pending_count" -gt 0 ]; then
+            summary="$summary
+
+ACTION REQUIRED: ${pending_count} output(s) have recipes but are not yet materialized. Use \`lc run\` to produce them."
+        fi
+    fi
+fi
+
+# Output as JSON
+escaped_summary=$(echo "$summary" | jq -Rs .)
+echo "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": $escaped_summary}}"
+
+exit 0

lightcone/cli/claude/lightcone/scripts/validate-on-save.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# PostToolUse hook: Auto-validate ASTRA files after modification
+# Triggers on Write|Edit of astra.yaml or universes/*.yaml
+
+# Read JSON input from stdin
+input=$(cat)
+
+# Extract the file path that was modified
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+
+# Exit silently if no file path
+if [ -z "$file_path" ]; then
+    exit 0
+fi
+
+# Get the filename
+filename=$(basename "$file_path")
+dirpath=$(dirname "$file_path")
+dirname=$(basename "$dirpath")
+
+# Check if this is an ASTRA-related file
+is_astra_file=false
+
+# Check for astra.yaml (main analysis file)
+if [ "$filename" = "astra.yaml" ]; then
+    is_astra_file=true
+    file_type="analysis"
+fi
+
+# Check for universe files (in universes/ directory)
+if [ "$dirname" = "universes" ] && [[ "$filename" == *.yaml ]]; then
+    is_astra_file=true
+    file_type="universe"
+fi
+
+# Exit if not an ASTRA file
+if [ "$is_astra_file" = false ]; then
+    exit 0
+fi
+
+# Find the project root (where astra.yaml lives)
+if [ "$file_type" = "analysis" ]; then
+    project_root="$dirpath"
+else
+    # For universe files, go up one level
+    project_root=$(dirname "$dirpath")
+fi
+
+# Check if astra command is available
+if ! command -v astra &> /dev/null; then
+    # ASTRA CLI not installed, skip validation
+    exit 0
+fi
+
+# Run validation
+cd "$project_root" 2>/dev/null || exit 0
+
+if [ "$file_type" = "analysis" ]; then
+    result=$(astra validate astra.yaml 2>&1)
+    exit_code=$?
+else
+    result=$(astra validate "$file_path" 2>&1)
+    exit_code=$?
+fi
+
+# Prepare response
+if [ $exit_code -eq 0 ]; then
+    # Validation passed
+    echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PostToolUse\", \"additionalContext\": \"ASTRA validation passed for $filename\"}}"
+else
+    # Validation failed - provide context to Claude
+    # Escape the result for JSON (jq -Rs . adds quotes, so use it directly)
+    escaped_result=$(echo "ASTRA validation FAILED for $filename:\n$result" | jq -Rs .)
+    echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PostToolUse\", \"additionalContext\": $escaped_result}}"
+fi
+
+exit 0

lightcone/cli/claude/lightcone/skills/lc-build/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: lc-build
+description: >
+  Build an ASTRA analysis from spec to materialized results. Plans interactively,
+  then loops autonomously via ralph-wiggum until all outputs are verified.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(git:*), Bash(pip:*), Bash(mkdir:*), Bash(setup-lc-build:*), Agent, AskUserQuestion
+argument-hint: "[DESCRIPTION] [--universe NAME] [--max-iterations N]"
+---
+
+# /lc-build
+
+Two-phase build: plan interactively with the user, then loop autonomously until done.
+
+**Do NOT write or modify any code (scripts, astra.yaml, etc.) until the user approves the plan in Phase 1.** Phase 1 is read-only exploration and planning. Code changes only happen in Phase 2 (the loop).
+
+## Phase 0: Check for Interrupted Loop
+
+Before anything else, check if a previous loop was interrupted:
+
+```
+if .claude/ralph-loop.local.md exists:
+```
+
+If it exists, ask the user via `AskUserQuestion`:
+- "A previous lc-build loop was interrupted. Would you like to resume where it left off or start fresh?"
+- Options: "Resume the loop", "Start fresh (discard previous state)"
+
+**If resume:** Run the setup script in resume mode to claim the loop for this session:
+```
+bash .claude/skills/lc-build/scripts/setup-lc-build.sh --resume
+```
+Then jump straight to reading `.claude/ralph-loop.local.md` and following the loop prompt.
+
+**If start fresh:** Delete the old state file (`rm .claude/ralph-loop.local.md`) and continue to Phase 1.
+
+## Phase 1: Setup & Plan
+
+### 1. Validate prerequisites
+
+Run the setup script in validate mode:
+
+```
+bash .claude/skills/lc-build/scripts/setup-lc-build.sh --validate --universe <UNIVERSE> --max-iterations <N>
+```
+
+Default universe is `baseline`, default max-iterations is `25`. Parse these from the user's arguments.
+
+If validation fails, fix issues before proceeding (create `astra.yaml` via `/lc-new`, fix validation errors, etc.).
+
+### 2. Create implementation plan
+
+Read `astra.yaml`, `CLAUDE.md`, `.claude/guides/astra-reference.md`, `.claude/guides/lightcone-cli-reference.md`, `universes/<UNIVERSE>.yaml`, and any existing `scripts/` directory. If the user provided a description (e.g. `/lc-build focus on the fitting script first`), use it to guide the plan's priorities and ordering. Produce an ordered implementation plan and write it to `.lightcone/plans/build-plan-<UNIVERSE>.md`.
+
+The plan must include:
+
+1. **Analysis overview** — project name, universe, input data, container, execution target
+2. **Dependency graph** — which outputs depend on which
+3. **Decision selections** — table of decisions and their selected values for this universe
+4. **Ordered build checklist** — for each output: script, decisions, dependencies, estimated cost
+5. **Verification checklist** — spec validation, decision-code alignment
+
+### 3. Present plan for approval
+
+Print the plan contents and ask the user via `AskUserQuestion`:
+
+- "Does this build plan look good?"
+- Options: "Approve and start building", "Let me edit the plan first"
+
+If the user wants changes, wait for them to edit `.lightcone/plans/build-plan-<UNIVERSE>.md` and re-present.
+
+## Phase 2: Activate Loop
+
+Once the user approves the plan, activate the autonomous loop:
+
+```
+bash .claude/skills/lc-build/scripts/setup-lc-build.sh --activate --universe <UNIVERSE> --max-iterations <N>
+```
+
+This creates `.claude/ralph-loop.local.md` — the ralph-wiggum state file. The stop hook will now intercept exits and re-inject the build prompt.
+
+**Begin the first iteration immediately.** Read `.claude/ralph-loop.local.md` — the rendered loop prompt is everything after the YAML frontmatter. Follow it: survey, decide what to do, work, commit, exit. On exit, the stop hook re-invokes you with the same prompt for subsequent iterations until you output `<promise>BUILD_COMPLETE</promise>` or hit max iterations.
+
+## References
+
+- [Loop Prompt](./assets/loop-prompt.md) — the invariant prompt for each iteration
+- [lightcone-cli Verify](../lc-verify/SKILL.md) — verification checks
+
+## Notes
+
+- The setup script will attempt to install the ralph-loop plugin if missing (via marketplace update). If installation fails, it errors and cleans up — the loop cannot run without the stop hook.
+- The build plan file (`.lightcone/plans/build-plan-<UNIVERSE>.md`) persists across crashes for easy resumption. It's deleted on successful completion.
+- To cancel mid-loop: `/cancel-ralph`

lightcone/cli/claude/lightcone/skills/lc-build/assets/loop-prompt.md

@@ -0,0 +1,92 @@
+You are inside a lc-build loop (universe: {{UNIVERSE}}). Each iteration: survey, work, commit, exit. The stop hook re-invokes you with this prompt until you're done.
+
+## Survey
+
+Run these commands and read their output:
+
+1. `lc status --universe {{UNIVERSE}}` -- what's materialized, what's pending, what has no recipe
+2. `git log --oneline -10` -- what happened recently
+3. `astra validate astra.yaml` -- is the spec valid
+4. Read `.lightcone/plans/build-plan-{{UNIVERSE}}.md` -- your implementation plan (cross off completed items as you go)
+
+## Decide What to Do
+
+**Follow the plan.** Read `.lightcone/plans/build-plan-{{UNIVERSE}}.md` and work on the next unchecked item. The plan was designed with the right ordering — shared utilities before scripts that use them, upstream outputs before downstream ones. Trust it.
+
+If the plan is fully checked off or doesn't cover what `lc status` reveals, fall back to the status-based rules below.
+
+### `astra validate` fails → Fix the spec first
+
+Always fix validation errors before doing anything else. Commit. Exit.
+
+### All outputs show `ok` → Verify & Complete
+
+All outputs are materialized. Time to verify.
+
+1. **Inline checks:**
+   - `astra validate astra.yaml` passes
+   - `lc status --universe {{UNIVERSE}}` shows all `ok`
+   - Decision-code alignment: `grep -r "add_argument" scripts/` and compare against `astra info --decisions` — every decision must be a parameter, no hardcoded values
+2. **If any issues found:** fix them, re-materialize if needed, commit. Exit (loop continues).
+3. **If all clean:** Spawn a verification sub-agent with explicit steps (do not rely on skill dispatch — the sub-agent cannot invoke `/lc-verify` directly):
+   ```
+   Agent tool, subagent_type: general-purpose
+   Prompt: "Verify the spec, code, and results all agree for universe {{UNIVERSE}}. Run these checks in order:
+   1. Spec validation: run `astra validate astra.yaml` — must pass with no errors.
+   2. Materialization status: run `lc status --universe {{UNIVERSE}}` — every output must show `ok`.
+   3. Decision-code alignment (most important): run `astra info --decisions` and `grep -r 'add_argument' scripts/`. Every decision in the spec must be accepted as a CLI parameter in the code, with no hardcoded values.
+   4. Results match spec: for every output in astra.yaml, confirm `results/{{UNIVERSE}}/<output_id>.<ext>` exists and looks well-formed. For `type: metric` outputs, check for valid `{'value': ...}` JSON.
+   Report all findings with file paths and line numbers. If all checks pass, end your report with exactly: VERIFIED"
+   ```
+4. **If sub-agent reports issues:** fix them, commit. Exit (loop continues).
+5. **If sub-agent says VERIFIED:** Output exactly: `<promise>BUILD_COMPLETE</promise>`, then clean up the build plan (`rm .lightcone/plans/build-plan-{{UNIVERSE}}.md`).
+
+## Reference: How Work Gets Done
+
+These are the kinds of work you'll do, guided by the plan. Not a rigid sequence — the plan determines the order.
+
+### Writing scripts
+
+1. **Write the script.** Parameterize all decisions from `astra.yaml` as command-line arguments (underscore convention: `stellar_mass_cut` → `--stellar_mass_cut`).
+   The script must contain real, functional logic that produces genuine results from actual input data. No `# TODO` stubs, no hardcoded dummy values standing in for computation, no `pass` in place of real logic, no synthetic/mock data generation when real data is specified. If you cannot implement the full logic (e.g., missing a library or unclear algorithm), document the blocker in the build plan and move on — do not ship a fake version.
+2. **Test locally:** `python scripts/<name>.py --decision1 value1 --decision2 value2` using values from `universes/{{UNIVERSE}}.yaml`.
+   Note: manual script runs may write to `results/` but do NOT register as materialized.
+   Only `lc run` creates the Dagster events that `lc status` recognizes.
+3. **Debug until it works.** Read tracebacks, check imports (`python -c "import module"`), verify decision parameter names match `astra.yaml`.
+4. **Commit** with a message describing what the script does.
+
+### Adding recipes & materializing
+
+1. **Add the recipe block** to `astra.yaml` under the output's `recipe:` key.
+2. **Validate:** `astra validate astra.yaml`
+3. **Check execution environment:** If the target is SLURM, check `echo $SLURM_JOB_ID`. If empty, you are on a login node — warn the user to start an interactive allocation (`salloc`) before running. Do not submit batch jobs during the build loop; interactive execution is required for fast iteration.
+4. **Run it:** `lc run <OUTPUT> --universe {{UNIVERSE}}`
+5. **If it fails:** Read the error output carefully and diagnose the root cause before retrying. Never re-run the same command without changing something first. Common causes:
+   - Container not built → `lc build`
+   - Upstream not materialized → materialize dependency first
+   - Script error inside container → fix the script, then re-run
+   If a second attempt also fails, note the failure in your commit message and in the build plan, then move on to other work. Come back to it in a later iteration with fresh context.
+6. **If it succeeds:** Verify the result file exists at `results/{{UNIVERSE}}/<output_id>.<ext>` and looks well-formed.
+7. **Commit** with a message noting what was materialized.
+
+## Rules
+
+**Work on 1-3 things per iteration.** Do NOT try to clear the entire queue. Exit after substantial progress so the next iteration gets fresh context.
+
+**Exit before compaction.** Exit the iteration when ANY of these apply:
+- You have materialized an output or made a failed attempt at one
+- You have written or substantially modified more than 2 scripts
+- A command produced more than ~200 lines of output
+- You are on your 3rd or later `lc run` invocation this iteration
+- You have read the same file more than once this iteration
+Do not wait until context feels tight. Exit early and often — the next iteration gets fresh context and costs nothing.
+
+**Commit messages are memory.** The next iteration discovers what you did via `git log`. Write descriptive commit messages.
+
+**Trust the spec.** `astra.yaml` is the source of truth. Don't ask permission, don't second-guess decisions. Build what it says.
+
+**Update the plan.** After completing work, edit `.lightcone/plans/build-plan-{{UNIVERSE}}.md` to cross off completed items and add notes about what you learned.
+
+**Document blockers.** If you hit something you can't resolve (missing data, ambiguous spec, external dependency), add it to the Open Questions section in `CLAUDE.md` and move on to other work.
+
+**No placeholders.** Every script must perform real computation on real data. Code that fakes results — hardcoded return values, TODO stubs, synthetic data standing in for real inputs — is worse than no code at all. If you cannot implement something fully, skip it and document why in the build plan.