Reference tooling

OPFiles names ten command verbs. This page documents nine: init, import, doctor, render, migrate, sync, upgrade, absorb, and record; the tenth, adopt, is documented in the adoption command reference. Of these nine, the reference CLI implements five. The ordinary import modes are retired and refuse with exit 2; upgrade refuses with exit 2, since the reference tooling defines no store upgrade; migrate and sync are planned and currently exit 2 (not yet implemented).

Status

The standard is a draft, and so is the reference suite below. A base adopter can use their own tooling instead, or adopt by hand. The turnkey walkthrough, a start-to-finish sequence with real command output, is a future section of this page: it will be written only from an observed run, never transcribed from design intent.

Commands

The command vocabulary

`opf init`

Scaffolds validated store sources and the committed pointer; surfaces, never absorbs, anything already at the store location.

`opf render`

Regenerates declared views. --check compares bytes read-only. --write gates on source integrity, then checks source integrity and regenerated outputs after writing; other deliverable failures can remain and cause a nonzero exit.

`opf doctor`

Runs the whole-store integrity layer read-only and returns a valid, invalid, or cannot-evaluate verdict.

`opf upgrade`

Refuses every command line with exit 2 and writes nothing: the reference tooling defines no store upgrade. In the standard, a later base-schema version bump ships its upgrade (spec 9.2).

`opf import`

Retired modes: --scan, --plan, --review, and --apply refuse with exit 2 and write nothing. Clean-start adoption is the intake; post-adoption import will use the approved prompt pack (spec 14.1).

`opf absorb`

Drafts changelog entries for human curation or computes a curated entry's freeze digest; outputs to stdout without writing files.

`opf record`

Authors one record change at a time: creates a record, transitions its status, completes a backlog item with its receipt, or appends a worklog entry. It leaves the change uncommitted for your review.

`opf migrate`

Planned: relocate the whole store, preserving git history and worklog. Not yet implemented in the reference CLI (exit 2).

`opf sync`

Planned: the surfaced pull and push step of the store consistency contract. Not yet implemented in the reference CLI (exit 2).

Coverage

What the tooling checks

When it runs, opf doctor covers the integrity layer:

Schema validity ID uniqueness and counter monotonicity Bidirectional index reconciliation Transition legality where observations suffice The all-or-none resolution bundle Byte drift for declared baseline views (inline layout) The root VERSION deliverable (required whenever releases exist, absent before the first release) Worklog span tiling and frozen digests Changelog coverage and freeze Archive integrity The tracked-store requirement Pointer and sync-target agreement Path containment

Doctor reports per-record view drift and the content schemas of module-tier and importer records, including legacy_fragment, as cannot-evaluate. Baseline view coverage includes composed views and projections. A declared view outside the baseline set, such as a module-type index mirror, makes the whole drift check cannot-evaluate. Transition checks also report cannot-evaluate when legality depends on an unidentified last-transition actor or a rejection requires unavailable pre-proposal state. Doctor does not check behind, ahead, or divergence against a sync target.

At the strictest posture, an unreadable, unparseable, or unresolvable declared input is a failure, never an empty or clean result.

Integrity

Trust and integrity

Before applying a downloaded pack, compare its digest with the independently published reference at posluns.dev/hashes.txt for that release. Refuse on a mismatch or missing evidence; the presence of this instruction does not establish that a reference is currently available.

Publishing a verifiable signature alongside releases is a roadmap item.

The reference tooling declares its release identity and the spec_version, homes generation, and worklog storage generation it supports (OPF-SPEC section 16.1) in one file, the declaration file opf/tools/opf-declaration.toml. The shipped-file digest is carried in opf/tools/_opf_declaration.py as SHIPPED_DECLARATION_SHA256. This release declares:

release = "1.0.5"
spec_version = "1.2.0"
homes = 1
worklog = 1

Before render, doctor, init, absorb, record, or adopt resolves a store, the tooling checks the installed copy of that file against that digest and against its own build. A copy that is absent, unreadable, altered, malformed, or contradictory refuses the command with exit 2 before any store is resolved. python3 -I -B opf/tools/opf.py --declaration runs that check alone and prints the report: the declaration as shipped, both digests, and the runtime result. opf doctor appends the same report.

Discovery

How an assistant finds the standard

The site provides an /llms.txt index and /adopt.md guide, also linked from the root page. Ask your assistant to read them, inspect your project, and propose a plan for review.

Relationship

Relationship to the reference suite

This tooling is part of the AIQT Guardrails reference enforcement suite. It is a consumer of the standard, not its definition: a base adopter can use their own tooling, or adopt by hand (see adopt by hand), and still align with the specification using their own checks. The standard defines the store and the command vocabulary; the reference implementation is one way to work them.