Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,23 @@ fields (#88)

==== Documentation

* docs(quickstart): rewrite QUICKSTART-DEV/USER/MAINTAINER and
docs/QUICKSTART against the repository as it actually is — real rustup +
cargo/`just` workflow (MSRV 1.85, bundled SQLite needs a C compiler), real
recipes, real artifact paths (`cargo install --path .`,
`target/release/verisimiser`), and an honest "not ready" list for the
Containerfile, devcontainer, Nix and Tier 2. Drops every RSR-template
placeholder and the recipes that never existed (`just setup`,
`just e2e`, `just check-error-codes`, `just panic-scan`, `just llm-context`,
`just build-release`, `just stapeln-*`, `just uninstall`)
* feat(just): `just doc-recipes` + `scripts/check-doc-recipes.sh` fail when a
documented `just` recipe is undefined, so quickstarts cannot drift from the
Justfile again
* docs: stop claiming unreleased/absent artifacts — no published release
(no tags yet), Containerfile is a template stub rather than a working OCI
build, and there is no `flake.nix`; TEST-NEEDS de-hardcoded from
`/var/mnt/eclipse/...` and refreshed to the current 146 unit / 23 integration
tests
* docs(adr): 0014-modality-vocabulary — unqualified *Octad* is
VeriSimiser's concern Octad; upstream is always *VeriSimDB's Octad*;
Tier 2 is a six-member overlay modality set with per-manifest enabled
Expand Down
36 changes: 36 additions & 0 deletions CONTRIBUTING-DEV.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,42 @@ backends.
a *new* overlay changes the set's membership and so needs an ADR,
not just a README edit (ADR-0014 §14.3).

== Commands in docs must exist

Documentation is treated as an interface: if a guide tells someone to run a
command, that command has to work. The RSR templates this repo started from
referenced recipes from other projects, so several guides shipped instructions
that failed with `Justfile does not contain recipe`.

* **Only reference recipes that the Justfile (or an imported `*.just`) defines.**
`just --list` is authoritative.
* **`just doc-recipes`** runs `scripts/check-doc-recipes.sh`, which fails if any
`.adoc` code block mentions an undefined recipe. Run it after editing docs.
* **Do not add a recipe just to satisfy a doc.** ADR-0002 removed aspirational
recipes that wrapped things which did not exist; the fix direction is to
correct the docs, not to invent the recipe.

Known non-recipes, with the real alternative:

[cols="2,2",options="header"]
|===
| Mentioned in old docs | Actually

| `just setup`, `just setup-dev` | `cargo fetch` / `just deps` (`./setup.sh` falls back to `just doctor`)
| `just check-error-codes` | No error-code catalogue exists in this repo
| `just e2e` | `just test` (`tests/` holds the integration + e2e suite)
| `just panic-scan` | `just assail`
| `just llm-context` | read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md`
| `just build-release` | `just build`
| `just install --prefix=…` | `cargo install --path . --root <prefix>`
| `just stapeln-*`, `just uninstall`, `just init` | Not present
|===

Template artifacts that are sync-managed from `hyperpolymath/standards`
(`docs/RSR_OUTLINE.adoc`, `container/*`, `.machine_readable/**`) still describe
the template's own recipes; `just doc-recipes` reports and skips the one it
scans rather than rewriting synced content.

== Style notes

* **Vocabulary** (ADR-0014): unqualified `Octad` means VeriSimiser's
Expand Down
5 changes: 5 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,11 @@ assail:
# `start`, `drift`, `provenance`, `history`, `status`, `octad`).
# Re-add wrappers here when their underlying subcommands ship.

# Verify that every `just <recipe>` in the docs is actually defined here.
# Guards against template leftovers (just setup / e2e / check-error-codes).
doc-recipes:
./scripts/check-doc-recipes.sh

# Run contractile checks (informational only — not required by CI per ADR-0008)
contractile-check:
@echo "Running contractile validation..."
Expand Down
Loading