Overview#

Use the failed operation, exact error and persisted state to diagnose a refusal. Keep operational observations private; this guide defines recovery rules, not a historical execution verdict.

Safety classification before running#

Read-only/local: generate-example-catalogs --check, default verify-reference-evidence, check-upstream-drift --skip-network, docs-corpus ..., reference-record get.
Local mutation: catalog/record add-edit-remove, generator without --check, analyzers, guidelines, verify --apply.
Network mutation: crawl, discovery, product scraping, image collection, README sync.
Operator/fleet state: width capture, accessibility audit, real product capture.

Use a dedicated corpus for qualification and check spis corpus status before mutation. An adopted corpus takes precedence over the working directory. Keep generated qualification state under an ignored build directory rather than copying a checkout or using operator production data.

Index regeneration refusals#

Record and catalog operations use the maintained Rust generator. A regeneration failure can follow a primary record change, so inspect reference-record get and the relevant source records before repeating add or remove.

Resolve the actual schema, provenance or retained-byte invariant reported by the generator, then regenerate and check its result. Do not hand-edit generated totals or use a retired dispatcher.

bash

spis generate-example-catalogs
spis generate-example-catalogs --check

Rust release identity#

Build the maintained CLI with cargo build --release and invoke target/release/spis.

Version source: both release staging and .wisent-release.json read the package version from Cargo.toml.

The Rust executable is the supported command surface. Retain its exact source identity with qualification evidence; a configured or running process alone does not prove its consumer works.

Catalog gate refusal#

Run the non-writing gate first:

bash

spis generate-example-catalogs --check

Common source messages identify the violated invariant: schema mismatch, count mismatch, unavailable local evidence, byte count differs from file, SHA-256 differs from file, unknown provenance class, duration below the 0.2-second floor, too few states/interactions/journey steps, or status contradicts gaps.

Fix the source record or retained evidence. Do not hand-edit generated README/index totals to match a broken source.

Verification prints gaps but exits 0#

This is expected. Default verification says:

text

dry run: records are measured and reported, nothing is written

It then prints completeness totals and grouped gaps. Exit 0 means measurement completed, not that every record is complete. Use --apply only when rewriting measurements is intended, then rerun the catalog gate through the normal evidence process.

Local drift#

bash

spis check-upstream-drift --skip-network

local media missing > 0: restore or intentionally remove/reclassify the record; inspect the listed path.
local media hash mismatch > 0: determine whether bytes changed legitimately. Never update a hash merely to silence drift.
--strict: exits 1 on either condition.

A zero mismatch count applies only to the bytes actually inspected in that invocation. It does not establish upstream freshness, accessibility coverage or a complete product journey.

Network drift categories#

The command separates:

reachable/unchanged;
gone;
guarded (authentication, rate limit, bot wall);
unresolved transport/network failure.

A guarded or unresolved source is not equivalent to deletion. Use --skip-readme to omit README SHA checks while still probing other URLs, or --skip-network for a local-only run. --write-report retains actual observations in .build/upstream-drift.json under the active corpus. Keep this operational report excluded from version control and publication.

Docs crawl#

pass --site <NN-slug> or --all: select a site or all.
unknown site: SLUG: choose a stem present in documentation-site-examples/content-structure/.
Interrupted crawl: rerun the same selection; state.json is periodically flushed and already-seen URL hashes are skipped.
Search returns zero with empty HOME: expected until pages.jsonl.gz exists.
url not found in the SLUG corpus (or archive still being written): verify exact URL; a concurrent gzip member may be incomplete.

Stado/Weles work#

Exact refusal when Stado cannot be resolved:

text

stado is not on PATH; hosts are reached through stado, never ssh

Use the trusted Stado executable; do not bypass it with SSH. Without an explicit host, capture and audit commands use the registry's active weles-admission placement. Audit accepts --target; width capture accepts --host. Accessibility execution waits through Stado and then reads terminal status, not a caller-supplied polling deadline. A dry-run validates only the plan and is not qualification.

Private audit evidence#

The active corpus's ignored .build/accessibility-audit/ directory retains plans, staging downloads and index.json. The index identifies the actual target, failed operation and per-record state after dispatch. Enqueue or terminal-status failure exits 2; retrieval or verification failure exits 3. Correlate the index's batch with the command you ran, and never publish these operational details as corpus records.

Planning can fail before a new index exists; an older index is not the result of that refusal. An explicit --plan outside the private directory is refused before dispatch. A completed measurement requires validated downloaded bytes and the corresponding persisted record, not merely an available host or a nonempty report.

PTY capture#

capture-cli-references --list executes each planned product's version probe; it is not a static list, and the products themselves come from the plan named with --plan, never from the binary. Normal capture refuses not on PATH: ... for selected missing binaries, and no monospace font to render the state PNGs: none of /System/Library/Fonts/Menlo.ttc, /System/Library/Fonts/SFNSMono.ttf could be read as a font before capturing when neither font is present. A session may report session failed mid-run: ...; keep the cast/run directory for diagnosis and do not represent it as complete evidence.

Credential recovery#

Follow the repository's credential recovery rule. Do not place tokens in documentation, command lines committed to history, or corpus records.