Add /lc-report skill: author MyST reports referencing ASTRA elements by path

CLAUDE.md

@@ -68,7 +68,7 @@ src/lightcone/              # namespace — NO __init__.py
 
 claude/lightcone/           # Claude plugin source — force-included into the wheel
 ├── skills/                 # lc-new, lc-from-code, lc-from-paper,
-│                            # lc-feedback, ralph;
+│                            # lc-report, lc-feedback, ralph;
 │                            # paper-reproduction bundle: lc-from-paper (entry),
 │                            # ralph (loop substrate),
 │                            # paper-extraction, figure-comparison,

claude/lightcone/scripts/session-start.sh

@@ -54,8 +54,11 @@ Substrate CLIs (use --help on any):
   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"
+  /astra   — astra.yaml spec: decisions, prior_insights, findings, evidence, sub-analyses, composition
+  /lc-cli  — lc workflow: spec-code invariant, status interpretation, failure diagnosis
+
+Report authoring:
+  /lc-report — draft/extend the MyST report (index.md): references spec elements by path, never hard-types results"
 
 if [ "$validation_ok" -ne 0 ]; then
     # tail rather than head -- the leading lines are success markers

claude/lightcone/skills/README.md

@@ -9,6 +9,7 @@ Each subdirectory is one Claude Code skill: `SKILL.md` plus optional `references
 | `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-report` | Author the project's MyST report — the external write-up that references `astra.yaml` elements by tree-path via the MySTRA plugin. Invoked standalone ("write up the results") and from `lc-from-paper`'s REVIEW close-out. |
 | `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. |
 

claude/lightcone/skills/astra/SKILL.md

@@ -357,6 +357,8 @@ The **`universe:` field** in universe files selects which sub-analysis universe
 
 Per-element prose (what each Input, Output, Decision, Option, or Insight is and why) belongs on the elements themselves via `description`/`rationale`/`notes` -- those can be written from day one. The analysis-level `description` can be filled in at any time and is safe to leave short.
 
+Rich write-ups do not live in the spec at all: they are external MyST reports that reference analysis elements by tree-path (the `/lc-report` skill authors them; `lc init` scaffolds the template).
+
 ```yaml
 description: |
   A two-stage pipeline for Iris classification that demonstrates

claude/lightcone/skills/lc-from-code/SKILL.md

@@ -122,6 +122,8 @@ If the scan found existing results elsewhere in the project, compare them agains
 
 Then validate the spec and the provenance chain: `astra validate astra.yaml` and `lc verify`. Present summary to user.
 
+With outputs materialized, offer to draft the write-up: `/lc-report` authors the project's MyST report (`index.md`), referencing the freshly specced decisions and outputs by path.
+
 ## Rules
 
 - **Minimal changes.** Do not refactor, rename, reorganize, or "improve" existing code.

claude/lightcone/skills/lc-from-paper/SKILL.md

@@ -42,7 +42,7 @@ Eight phases (zero-indexed). ORIENT runs before the loop, in the user's main ses
 | 4 | IMPLEMENT | ralph iteration | [`references/implement.md`](references/implement.md) | `scripts/`, `requirements.txt`, recipes in `astra.yaml` |
 | 5 | RUN | ralph iteration | [`references/run.md`](references/run.md) | `results/<universe>/<output>/` |
 | 6 | COMPARE | ralph iteration | [`references/compare.md`](references/compare.md) | `comparison-report.{yaml,md}` |
-| 7 | REVIEW | user's main session | [`references/review.md`](references/review.md) | `REPRODUCTION-SUMMARY.md`, `/figure-comparison` HTML, resolved `open-questions.md`, finalized reproduction outcome |
+| 7 | REVIEW | user's main session | [`references/review.md`](references/review.md) | `REPRODUCTION-SUMMARY.md`, `/figure-comparison` HTML, resolved `open-questions.md`, MyST report (`index.md` via `/lc-report`), finalized reproduction outcome |
 
 COMPARE produces a verdict plus an opportunity assessment — not just pass / fail, but where the gaps are, how much they likely matter, and how they sit relative to the constitution's fidelity intent. A subsequent iteration decides whether to spend another IMPLEMENT round (close a gap that sits below intent) or land the reproduction at its current trajectory and log the gap into CLAUDE.md's Open opportunities. Once the COMPARE → IMPLEMENT loop terminates (verdict `pass`, or `partial` with the un-acted opportunities logged), a subsequent cold-survey iteration finds nothing left to do and flips the constitution's `status:` to `closed`. The loop terminates; REVIEW runs in the user's main session.
 
@@ -120,7 +120,7 @@ Each iteration's survey reads the workdir to determine what phase is next. File
 
 ## REVIEW close-out (after the loop)
 
-When the loop closes (the user reports back that the tmux session has exited, or `constitution.md`'s `status:` is `closed`), run REVIEW from the user's main session. See [`references/review.md`](references/review.md) for the full close-out: invoke `/figure-comparison` (mandatory) and optionally `/check-sentence-by-sentence`, walk `open-questions.md` with the user, draft `REPRODUCTION-SUMMARY.md`, propagate un-acted opportunities into CLAUDE.md, commit.
+When the loop closes (the user reports back that the tmux session has exited, or `constitution.md`'s `status:` is `closed`), run REVIEW from the user's main session. See [`references/review.md`](references/review.md) for the full close-out: invoke `/figure-comparison` (mandatory) and optionally `/check-sentence-by-sentence`, walk `open-questions.md` with the user, draft `REPRODUCTION-SUMMARY.md`, author the MyST report via `/lc-report`, propagate un-acted opportunities into CLAUDE.md, commit.
 
 REVIEW runs in your main session because `/figure-comparison` and `/check-sentence-by-sentence` both use `AskUserQuestion`, which isn't available inside ralph iterations.
 

claude/lightcone/skills/lc-from-paper/references/review.md

@@ -2,7 +2,7 @@
 
 The reproduction has converged: the constitution's `status:` is `closed` (after COMPARE returned `pass`, or `partial` with the un-acted opportunities logged, and the next cold-survey iteration found nothing left to do). The ralph loop's tmux session has exited. REVIEW runs back in the user's main session — the second of two interactive bookends, the first being ORIENT. It runs in the user's main session (not as an iteration) because both `/figure-comparison` and `/check-sentence-by-sentence` use `AskUserQuestion`, which isn't available inside detached ralph iterations.
 
-Its job is to render the validation surfaces, walk the user through the accumulated open questions, land the resolutions, and draft the final report — in one interactive arc. The Open opportunities list in CLAUDE.md already carries un-acted-on opportunities from the latest COMPARE (those iterations logged them directly); REVIEW just reads them.
+Its job is to render the validation surfaces, walk the user through the accumulated open questions, land the resolutions, and draft the final summary and MyST report — in one interactive arc. The Open opportunities list in CLAUDE.md already carries un-acted-on opportunities from the latest COMPARE (those iterations logged them directly); REVIEW just reads them.
 
 The phase name **REVIEW** is freed by the old pre-implement REVIEW phase folding into ARCHITECT, SPECIFY, LITERATURE, and IMPLEMENT as their per-iteration self-review passes. This close-out is what the previous shape called SUMMARIZE_RUN.
 
@@ -24,7 +24,8 @@ The phase name **REVIEW** is freed by the old pre-implement REVIEW phase folding
 - (Optional) `.lightcone/check-sentence-by-sentence.md` — `/check-sentence-by-sentence`'s claim audit (file:line or NOT FOUND per sentence)
 - `open-questions.md` — same file, but with `## Resolutions` section appended capturing what the user said for each entry
 - Edits to `astra.yaml` / `implementation-notes.md` / `universes/baseline.yaml` if any open-question resolution warrants a spec change
-- `REPRODUCTION-SUMMARY.md` — final report; concise (~1–2 pages); the canonical record of what the reproduction landed on
+- `REPRODUCTION-SUMMARY.md` — final summary; concise (~1–2 pages); the canonical record of what the reproduction landed on
+- `index.md` + `myst.yml` — the MyST report, authored via `/lc-report`: the rich, publication-shaped write-up that references `astra.yaml` elements by path
 - CLAUDE.md updates — **Paper-vs-code disagreements** entries reconciled with their resolutions (Open opportunities already there from COMPARE iterations)
 - A commit closing out the reproduction
 
@@ -74,13 +75,21 @@ A single markdown file at the project root, ~1–2 pages. The canonical record o
 
 Brief, not exhaustive. The depth lives in `astra.yaml` and the workdir's notes; the summary is the door into them.
 
-## Step 4: reconcile the Open opportunities list
+## Step 4: author the MyST report with `/lc-report`
+
+`REPRODUCTION-SUMMARY.md` is the concise close-out record; the MyST report is the rich, publication-shaped companion — Introduction / Methods / Results prose that references the spec's decisions, findings, and outputs by path and pulls reproduced numbers in live, so it can never drift from what the pipeline actually produced.
+
+Invoke `/lc-report` in paper-reproduction mode. It reads the spec, `work/reference/`, the comparison verdict, and the open-question resolutions from Step 2 — the divergence passages ("during reproduction we found…") come straight from those resolutions. If `index.md` / `myst.yml` don't exist yet (reproduction workdirs typically weren't scaffolded by `lc init`), the skill creates them. It validates with `myst build --html` before finishing; show the user how to preview (`myst start`).
+
+If the user prefers to skip the report, log it as an Open opportunity in CLAUDE.md instead of silently dropping it.
+
+## Step 5: reconcile the Open opportunities list
 
 COMPARE iterations have been logging un-acted-on opportunities into CLAUDE.md's *Open opportunities* list as they run, so the list is already populated. REVIEW's job here is reconciliation: cross-check that every opportunity in `comparison-report.yaml`'s `opportunities:` block that the user did NOT act on is present in CLAUDE.md's list, and remove any that the user acted on at REVIEW (e.g. authorized one more IMPLEMENT round to close).
 
-## Step 5: commit
+## Step 6: commit
 
-Stage `REPRODUCTION-SUMMARY.md`, `open-questions.md` (with resolutions), the updated CLAUDE.md, the final `astra.yaml`, the comparison artifacts, and any housekeeping changes. Commit with a message that names the verdict and the close-out:
+Stage `REPRODUCTION-SUMMARY.md`, the MyST report (`index.md`, `myst.yml`, any sub-analysis pages), `open-questions.md` (with resolutions), the updated CLAUDE.md, the final `astra.yaml`, the comparison artifacts, and any housekeeping changes. Commit with a message that names the verdict and the close-out:
 
 ```
 review: <paper-short-name> verdict <verdict>, summary at REPRODUCTION-SUMMARY.md
@@ -93,7 +102,8 @@ This commit is the durable mark that the reproduction has reached close-out. Fut
 - `comparison-report.yaml` verdict is `pass` (or `partial` with un-acted opportunities logged) ⇒ ready to close out
 - `.lightcone/comparison.html` exists ⇒ `/figure-comparison` rendered
 - `open-questions.md` has a `## Resolutions` section covering every entry ⇒ open-questions walkthrough done
-- `REPRODUCTION-SUMMARY.md` exists ⇒ final report written
+- `REPRODUCTION-SUMMARY.md` exists ⇒ final summary written
+- `index.md` drafted past the `lc init` TODO stub (or its skip logged as an Open opportunity) ⇒ MyST report authored
 - CLAUDE.md's *Open opportunities* list reflects the un-acted-on opportunities from the latest COMPARE ⇒ reconciliation done
 - A `review:` commit lands ⇒ REVIEW done; reproduction complete
 
@@ -104,5 +114,5 @@ This commit is the durable mark that the reproduction has reached close-out. Fut
 - **The user owns the verdict-acceptance decision.** REVIEW's purpose is to let the user see what the loop's iterations did and decide whether they accept it. The skill renders surfaces and asks; it does not unilaterally close.
 - **Don't confuse with the per-phase reviews inside the loop.** ARCHITECT, SPECIFY, LITERATURE, and IMPLEMENT each have their own fresh-context review discipline that happens by iteration boundary. Those are unrelated to this close-out — same word, different jobs. The phase boundary makes them unambiguous: per-phase reviews live inside their host phase's reference; this one is the post-loop close-out in the user's main session.
 - **Open-question resolutions are durable.** Append to `open-questions.md`'s `## Resolutions` section so the next re-run / future session sees what was decided. Do not delete the original questions.
-- **Keep the report short.** Long reports get skimmed; short reports get read. Two pages is generous.
+- **Keep the summary short.** Long summaries get skimmed; short summaries get read. Two pages is generous. Depth belongs in the MyST report (Step 4), which telescopes into the spec rather than restating it.
 - **Do not invent further work.** If the user has accepted the verdict and the opportunities are propagated, the reproduction is done. The next session, the user, or a future revisit can decide whether tightening any open opportunity still serves them.

claude/lightcone/skills/lc-new/SKILL.md

@@ -146,6 +146,8 @@ Show summary table:
 
 Then tell the user the spec is ready and they can begin implementation. Recommend running `/clear` first — the scoping conversation consumes significant context, and everything needed to continue is captured in `astra.yaml` and `CLAUDE.md`.
 
+Also mention the report: `lc init` scaffolded a template MyST report (`index.md` + `myst.yml`) that references the spec by path. `/lc-report` drafts it — the Introduction and Methods can be written as soon as the spec is stable; Results once `lc run` has materialized outputs.
+
 ---
 
 ## Restrictions