diff --git a/content/docs/agent-skills/lightcone.mdx b/content/docs/agent-skills/lightcone.mdx index 54f878a..9d96f62 100644 --- a/content/docs/agent-skills/lightcone.mdx +++ b/content/docs/agent-skills/lightcone.mdx @@ -188,7 +188,9 @@ integrates, so each intermediate result can be inspected: 4. **Materialize.** It runs `lc materialize local `, which remakes what is stale, dependencies first, and commits each output as it lands. -The work is done when `lc materialize --check` passes. A script that ran well under `lc run` is a +The work is done when `lc materialize --check` passes and `lc status` lists no output as +`no recipe`. The check covers only outputs that have a recipe, so an output declared without one +never fails it. A script that ran well under `lc run` is a probe, not a result: nothing counts until `lc materialize` has produced it. Each output lands at `results//.`, a path `lc` composes from the @@ -220,13 +222,14 @@ nothing a recipe sees. ### Status The agent reads `lc` through its `--json` output, and quotes the reason `lc` gives for each output -rather than inferring one. Each output is in one of three states: +rather than inferring one. Each output is in one of four states: -| State | Means | What happens | -| --------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| `current` | Matches the specification, made under this environment | Nothing | -| `behind` | Still matches the specification, but the environment has changed | Nothing, unless you want it remade | -| `stale` | Contradicts the specification, or its bytes were changed by something other than its run | The next `lc materialize` remakes it | +| State | Means | What happens | +| ----------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| `current` | Matches the specification, made under this environment | Nothing | +| `behind` | Still matches the specification, but the environment has changed | Nothing, unless you want it remade | +| `stale` | Contradicts the specification, or its bytes were changed by something other than its run | The next `lc materialize` remakes it | +| `no recipe` | Declared in the specification, with no recipe to make it | Skipped by `lc materialize` until a recipe is written | Every output going `behind` after a `uv add` is normal. Upgrading `lc` invalidates nothing. @@ -341,5 +344,5 @@ archive or cite the analysis, the agent: `ro-crate-metadata.json`, an [RO-Crate](https://www.researchobject.org/ro-crate/) description of the project rendered from the repository. -It is ready when validation passes, `lc materialize --check` passes, and `ro-crate-metadata.json` -exists. +It is ready when validation passes, `lc materialize --check` passes, `lc status` lists no output as +`no recipe`, and `ro-crate-metadata.json` exists. diff --git a/content/docs/lightcone-cli/commands/materialize.mdx b/content/docs/lightcone-cli/commands/materialize.mdx index eb7db5d..91c8984 100644 --- a/content/docs/lightcone-cli/commands/materialize.mdx +++ b/content/docs/lightcone-cli/commands/materialize.mdx @@ -97,7 +97,6 @@ stronger consent than a flag. ```json { - "ok": true, "up_to_date": true, "made": [], "current": ["baseline/fit", "robust/fit", "baseline/fit_plot", "robust/fit_plot"], @@ -110,12 +109,16 @@ stronger consent than a flag. } ``` -The first two keys are the ones to branch on: `ok` means everything attempted finished; -`up_to_date` means nothing needed doing (a failed run is never up to date, and `behind` outputs -don't count against it). `planned` is check mode's answer, mapping each would-run output to why; +There is no overall success key. `up_to_date` is the check's answer: nothing needed doing (a +failed run is never up to date, and `behind` outputs don't count against it). A run succeeded when +`failed` and `blocked` are empty. The exit code is 1 when any of `failed`, `blocked` or `planned` +is non-empty. `planned` is check mode's answer, mapping each would-run output to why; `behind` maps each left-alone output to the commit that can rebuild its environment. `notes` carries sandbox messages verbatim: denial remedies are built to be pasted. +An output declared without a recipe never appears in `planned`: a run skips it, so the check +passes over it. [`lc status`](/lightcone-cli/commands/status) lists it as `no recipe`. + ## Examples ```bash diff --git a/content/docs/lightcone-cli/commands/status.mdx b/content/docs/lightcone-cli/commands/status.mdx index 081b817..fc4d4cd 100644 --- a/content/docs/lightcone-cli/commands/status.mdx +++ b/content/docs/lightcone-cli/commands/status.mdx @@ -20,12 +20,13 @@ lc status [OPTIONS] mode: direct sandbox: landlock (fs: declared, network: allowed) - · current baseline/fit a3f1f11 - · current baseline/fit_plot a3f1f11 - · behind robust/fit 00cc14e made under an earlier environment - ! stale robust/fit_plot — no manifest — it has never been materialized + · current baseline/fit a3f1f11 + · current baseline/fit_plot a3f1f11 + · behind robust/fit 00cc14e made under an earlier environment + ! stale robust/fit_plot — no manifest — it has never been materialized + · no recipe baseline/summary — -2 current · 1 behind · 1 stale +2 current · 1 behind · 1 stale · 1 no recipe ``` The header is repository facts: which mode the project executes in (and, for a containerized @@ -44,6 +45,8 @@ commit is where the environment that produced it can be read back. `--refresh` remakes. - `stale`: contradicts the project: definition changed, an input's content changed, or the output was edited by hand since it was made (a *foreign write*; the offending commit is named). +- `no recipe`: declared by the spec, but with no recipe to make it. Runs skip it, and + `lc materialize --check` passes over it. Write its recipe to make it. ## Report vs gate @@ -51,6 +54,10 @@ commit is where the environment that produced it can be read back. different exit codes is how a script comes to depend on the wrong one, so the split is sharp: use status for eyes, check for exit codes. +The gate covers only outputs that have a recipe, because it predicts what a run would do and a run +skips the rest. An analysis is finished when the check passes and status lists no `no recipe` +output. + ## Options | Option | Default | Effect | @@ -64,7 +71,7 @@ status for eyes, check for exit codes. "mode": "direct", "image": null, "sandbox": "landlock (fs: declared, network: allowed)", - "counts": {"current": 4, "behind": 0, "stale": 0}, + "counts": {"current": 4, "behind": 0, "stale": 0, "no recipe": 0}, "outputs": [ { "output": "baseline/fit", @@ -79,7 +86,7 @@ status for eyes, check for exit codes. } ``` -Per output: the state, the reason (empty for `current`), the commit it was materialized at and its +Per output: the state, the reason (empty for `current` and `no recipe`), the commit it was materialized at and its content identity (both empty if it never was), and `foreign_write`: the sha of a hand-edit's commit when one was detected, which the prose `why` cannot carry for a machine consumer. For a containerized project, `image` is `{"tag": ..., "state": "present" | "absent" | "unfetched"}`. diff --git a/content/docs/lightcone-cli/concepts.mdx b/content/docs/lightcone-cli/concepts.mdx index 0c60213..9e300c7 100644 --- a/content/docs/lightcone-cli/concepts.mdx +++ b/content/docs/lightcone-cli/concepts.mdx @@ -178,9 +178,10 @@ no sandbox, the recipe still runs, and its manifest says so. - **`lc status`** shows each output's state and the commit it was made at. It runs nothing, works with uncommitted changes, and always exits 0. - **`lc materialize --check`** runs nothing either, and exits 1 if a run would make anything. Use it - in scripts and CI. + in scripts and CI. It covers only outputs that have a recipe: `lc status` lists any declared + without one as `no recipe`. -Both take `--json`. In the check's report, the `ok` and `up_to_date` keys are the ones to test. +Both take `--json`. In the check's report, `up_to_date` is the key to test. ## Publishing