lc-from-paper/specify.md documents a future astra-spec shape the installed 0.0.10 validator rejects

[cailmdaley]

What happened

.claude/skills/lc-from-paper/references/specify.md instructs the SPECIFY sub-agent to author astra.yaml blocks in a shape that the installed astra-spec (0.0.10) rejects wholesale. The skill bundle is written against what looks like a future 1.0 grammar; the runtime hasn't caught up. There is no early signal — astra validate prints a quiet "analysis declares ASTRA spec version 1.0, but astra-spec 0.0.10 is installed; validation reflects the installed version" warning at the top, then continues, so SPECIFY only discovers the mismatch after authoring entire decision/insight/finding blocks and round-tripping each one through astra validate.

Concretely, specify.md tells SPECIFY to author (paraphrased):

• prior_insights: placeholders with decision_links: mapping to options, plus doi: and claim: directly on the Insight
• decisions: with name: + description: at the decision level, and per-option rationale: + evidence: blocks
• evidence: blocks as TextQuoteSelector with source: and anchor: siblings

The 0.0.10 schema actually has:

• Insight: id, label, claim, created_at (required ISO datetime), evidence: list[Evidence]. No decision_links, no value, no doi on Insight. DOI lives on each Evidence under a strict ^10\\.\\d{4,}/.*$ pattern.
• Decision: id, label, rationale, tags, default, options: dict[str, Option]. No name, no description.
• Option: id, label, description, insights: list[str] (back-refs to prior_insight IDs), incompatible_with, requires, excluded, excluded_reason. No rationale, no evidence directly on the option — evidence lives only inside Insights.
• Evidence: id, doi or artifact, optional quote: TextQuoteSelector (just exact/prefix/suffix — no source, no anchor).

So decisions flow through prior_insights via Option.insights back-refs; evidence (and its quote selector) lives inside Insight, not on the decision/option/finding directly.

Reproduction

In a fresh lc-from-paper reproduction project against astra-spec 0.0.10, follow specify.md literally for any sub-analysis. Author a decisions: block with name: + per-option rationale: + per-option evidence: block as described in specify.md §"Pass A — paper pass". Run astra validate astra.yaml. The schema validator emits dozens of "Additional properties not allowed" / "Field required" errors per block. Same outcome for prior_insights: placeholders with decision_links: and findings: with value:.

What I'd ask for

• Either rebase specify.md (and the rest of lc-from-paper/references/, since they probably share this drift) onto the 0.0.10 grammar that ships with the harness today, or ship astra-spec 1.0 + the grammar specify.md actually documents
• Surface the mismatch louder than the current single-line warning — refuse to validate, or print a banner specifically when the analysis declares a version newer than the installed astra-spec

Related: I'm also filing an astra-spec validator bug separately (semantic.py:349 only looks at root prior_insights for Option.insights refs, breaking same-scope sub-analysis references), which I hit working around this docs mismatch.

Environment

• astra-spec: 0.0.10
• lightcone-cli: 0.3.4
• Python: 3.11.13
• Linux x86_64

— Claude on behalf of Cail

[cailmdaley]

Realigned in 2ffbda4 on add/narrative-skill (PR #86).

The rewrite of references/specify.md and references/literature.md brings them onto the 0.0.10 grammar:

• Decision-level rationale: — not per-option. Option carries {label, description, insights}; no per-option rationale: or evidence: block. The paper's chosen option is identified by default:.
• Option.insights: [<insight_id>, ...] is the back-reference that links options to prior_insights. Replaces the misplaced decision_links: field that previously lived directly on the Insight.
• prior_insights: placeholders are now syntactically-complete Insight blocks: id, claim, created_at, evidence: [{id, doi}]. The placeholder Evidence carries the cited paper's DOI but no quote: selector; LITERATURE writes quote: {exact, prefix, suffix} and location: {page: N} onto each Evidence entry later. Evidence with doi: and no quote: is structurally valid in 0.0.10 (quote: is optional on Evidence), so the placeholder passes astra validate and waits for LITERATURE.
• findings: entries are full Insights with paper-anchored Evidence: doi: of the target paper + quote: {exact, prefix, suffix} + location: {page: N}. Code-revealed findings use artifact: <output_id> (+ optional source_commit:) instead of free-form path:line evidence anchors.
• LITERATURE input contract surfaces backed_options — a derived list of <decision_id>.<option_id> pairs from Option.insights back-refs — in place of the dropped decision_links forward-link.

The two related side-asks weren't in scope here:

1. The agent-output decision_links: block in claude/lightcone/agents/lc-extractor.md is an intermediate format (not astra.yaml content); a downstream consumer needs to translate it into Option.insights back-refs at merge time. Leaving it for now; can split into a separate fix if you want to harden the lc-extractor → astra.yaml merge path.
2. Surfacing the spec-version mismatch louder than the current single-line warning is upstream of this skill bundle (astra-tools / astra-spec choice). The version: "1.0" in astra-reference.md's example block and in lc init's scaffold (ASTRA cli.py: _create_boilerplate_astra_yaml) is the source of the declared-version drift you saw at the top of astra validate output; a separate change could refuse to validate on declared-version-newer-than-installed.

The companion validator-scoping fix is filed as astra-tools#86 (closes #85). Both are needed end-to-end: this PR fixes the docs, the astra-tools PR makes Option.insights resolve against the natural same-scope authoring shape.

Closing once #86-on-this-repo lands.

— Claude on behalf of Cail