Record indexes

Template

Illustrative excerpt: the envelope fields (created_at, updated_at, actor) are omitted for brevity.

The shared index shape is schema = 1 plus [[record]] rows. The envelope requires id, type, status, title, timestamps, and actor.kind (maintainer, assistant, automation, or importer). Timestamps use RFC 3339 UTC; an importer may omit an unknown created_at with provenance. Optional fields include summary, proposed_from (present only on a /proposed status, written by opf record transition), links, refs, and registered x-<vendor> extensions. Links use the closed vocabulary supersedes, resolves, remediates, receipt_of, corrects, follows, relates, exemplifies, and derives_from. References identify a path, URL, or document. Schemas are closed; unknown keys are validation findings.

The problem it solves

Give planned work explicit identities and completion rules.

The standard gives each item a permanent ID, closed states, and ratification rules: an assistant or automation terminal transition lands with /proposed, and only a maintainer removes the qualifier. Blocked-ness is derived from active blocks at render time; the result still depends on the recorded blocks being current.

Pairs with

TODO.md BACKLOG.md PIPELINE.md

Three composed views draw on this index joined against blocks, all byte-drift-gated and rendering the actionability join. An optional BACKLOG_ITEM-INDEX.md mirror renders the index one-to-one for human reading.

Lifecycle

open → active → done | dropped

Open may go straight to dropped. No resurrection: a record in an unqualified terminal state never re-enters a working state, so a revived concern is a new record linking the old one. A ratified done creates a one-to-one completion receipt in the done index, and an item is actionable while open or active, not importer-authored, and with no unqualified active block from a non-importer actor scoping it. An importer-authored item is imported history: it is never actionable, whatever its recorded state.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index), then records by process as work is planned; updated by state transitions under the status grammar and maintainer ratification of proposed terminals; read by opf render and validated by opf doctor (schema validity, ID uniqueness, transition legality where observations suffice, no-resurrection). Actor-dependent transitions with an unidentified last-transition actor and rejections requiring unavailable pre-proposal state report cannot-evaluate.

What it protects

Template

Illustrative excerpt: title, created_at, updated_at, and actor are omitted for brevity.

The shared index shape (schema = 1 plus [[record]] rows) with the standard envelope and no type-specific extra fields. The single state is recorded, with no transitions and never proposable: a factual receipt awaits no ratification, so it carries no /proposed qualifier. It links receipt_of to the backlog item it witnesses; a standalone receipt is legal only for imported history with provenance.

The problem it solves

Completion needs its own artefact.

If "done" were only a state flag on the backlog item, the moment of completion, who ratified it, and what it covered would be reconstructable only from history. A separate immutable receipt makes each completion a first-class, linkable fact.

Pairs with

DONE.md

Composed from this index, plus the optional DONE-INDEX.md mirror; both byte-drift-gated.

Lifecycle

recorded (terminal only)

A single state, no transitions, and never proposable. A ratified backlog done requires a receipt in the same act, one to one; imported standalone receipts require provenance. Receipts may rotate under manifest-declared thresholds, preserving their IDs and archived content.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index), by the ratified-done transition, and, as migrated history with provenance, by import (the reference CLI's retired importer, or post-adoption import, which the reference CLI does not implement yet); never updated, since records are immutable, though rotation relocates aged receipts to the archive; read by opf render (DONE.md and the mirror) and validated by opf doctor (schema, uniqueness, the one-to-one receipt link).

What it protects

Template

Illustrative excerpt: title, created_at, updated_at, and actor are omitted for brevity.

The shared index shape with the standard envelope plus one type-specific field, severity. Links typically carry remediates toward the backlog item or change that fixes the finding; refs capture the evidence (a path and line, a URL, or a document and section) at the moment the claim is made.

The problem it solves

Record defects with permanent IDs and explicit outcomes.

The standard requires severity grading at or after the fix decision. An assistant or automation terminal transition carries /proposed until maintainer ratification.

Pairs with

FINDINGS.md

Composed from this index, plus the optional FINDING-INDEX.md mirror; both byte-drift-gated.

Lifecycle

open → fixed | routed | refuted | accepted

Four terminal outcomes, all proposable: fixed (remediated), routed (sent to its real owner), refuted (the observation did not hold), accepted (a recorded decision to live with it). No resurrection: a concern that returns is a new finding linking the old one.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index) and by whoever observes a defect, human or assistant; updated by resolution transitions, maintainer ratification, and severity grading at or after the fix decision; read by opf render (FINDINGS.md and the mirror) and validated by opf doctor (schema, uniqueness, transition legality where observations suffice). Actor-dependent transitions with an unidentified last-transition actor and rejections requiring unavailable pre-proposal state report cannot-evaluate.

What it protects

Template

Illustrative excerpt: title, created_at, updated_at, and actor are omitted for brevity.

The shared index shape with the standard envelope plus the resolution bundle fields: decision, decided_at, and decided_by. An open decision carries none of the three; a decided one carries all three. A decided record may be superseded by a new decision linking supersedes; the decision-resolution join walks that chain to find the current effective resolution.

An importer-authored decision is imported history: the join never makes it the current effective resolution, and its supersedes links take no decision out of current authority, so a non-importer decision it supersedes stays current. A new non-importer decision that supersedes an importer-authored one is the current effective resolution of its chain. The chain is every decision its supersedes links connect, through any decision including a proposal, so where importer-authored decisions join non-importer decisions that stay current into one chain, that chain has more than one current effective resolution: opf render stops with a cannot-evaluate before writing any view, and a clean chain beside it is not rendered either. The views read the active index only, not the archive: a chain that runs through an archived decision is evaluated over its active decisions alone, so two current resolutions that only an archived decision joins into one chain are not refused there, although opf doctor reads archived decisions beside active ones when it counts a chain's resolutions.

The problem it solves

Half-recorded decisions are worse than none.

An incomplete bundle omits part of the decision or its attribution. Validation rejects a partial resolution, and the decision-resolution join derives the effective answer through supersession links.

Pairs with

DECISIONS.md DECISIONS.toml

The composed DECISIONS.md (drawing on all four decision types) and the machine projection DECISIONS.toml, both byte-drift-gated, plus the optional PENDING_DECISION-INDEX.md mirror.

Lifecycle

open → decided | withdrawn

Both terminal states are proposable: an assistant-recorded resolution lands with the /proposed qualifier until a maintainer ratifies it. Overturning a decided question is a new record that supersedes the old; the old record is never edited back to open.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index) and whenever a question is parked for decision; updated by the deciding transition with its full bundle and by supersession from later decisions; read by opf render (DECISIONS.md, DECISIONS.toml, the mirror) and validated by opf doctor (schema, the all-or-none bundle, exactly one effective resolution per chain).

What it protects

Template

Illustrative excerpt: title, created_at, updated_at, and actor are omitted for brevity.

The shared index shape with the standard envelope plus scopes, the enumerated record IDs the block covers. States: active (initial; gated for assistant and automation actors) to released or expired (terminal). Blocked-ness is never stored on the scoped records; it is derived at view time through the block join.

The problem it solves

"Blocked" is one of the easiest states to abuse: it can park inconvenient work indefinitely.

The standard makes a block a scoped, auditable record rather than a mood, and gates its creation: a block created by an assistant or automation is active/proposed, a proposal that hides nothing and justifies no stop until a maintainer ratifies it. The gate applies to assistant and automation actors; an unqualified active block from a maintainer also counts toward blocked-ness. An importer-authored block is imported history and hides nothing, whatever its recorded state.

Pairs with

BLOCKS.md TODO.md BACKLOG.md PIPELINE.md

BLOCKS.md is composed from this index, and the block join renders inside TODO.md, BACKLOG.md, and PIPELINE.md; an optional BLOCK-INDEX.md mirror completes the set. All byte-drift-gated.

Lifecycle

active (gated) → released | expired

An unqualified active block from a non-importer actor hides the records it scopes from actionable views; a proposed or terminal block, and any importer-authored block, hides nothing. The block-actionability join is one of exactly two named joins in the closed transform vocabulary. Active blocks never rotate to the archive.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index), by maintainers directly, and by assistants as gated proposals; updated by ratification, release, or expiry transitions; read by opf render (BLOCKS.md and the actionability join in the three backlog views) and validated by opf doctor (schema, gated-state legality, scoped-ID resolution).

What it protects

Template

Illustrative excerpt: title, created_at, updated_at, and actor are omitted for brevity.

The shared index shape with the standard envelope and no type-specific extra fields; the handoff's content rides summary, links, and refs. States: current (initial) to superseded (terminal).

The problem it solves

Record the state needed for the next session.

A records-first discipline resumes from the durable handoff rather than starting cold, and the single-current rule means there is never ambiguity about which snapshot is authoritative. A handoff records where the work stands, what is in flight, and what comes next.

Pairs with

HANDOFF.md

Composed from this index, plus the optional HANDOFF-INDEX.md mirror; both byte-drift-gated.

Lifecycle

current → superseded

Posting a new handoff supersedes the previous one in the same act, so at most one current handoff exists; supersession is atomic with posting, the new handoff and the old one's terminal transition landing together. The current handoff never rotates to the archive, and the chain of superseded handoffs remains a readable history of how the work's state evolved.

Referenced by

opf init opf render opf doctor

Created by opf init (empty index) and by a new record at each session close or state checkpoint; updated only by supersession, in the same act as the next handoff's posting; read by session resume, by opf render (HANDOFF.md and the mirror), and validated by opf doctor (schema, the at-most-one-current invariant).

What it protects

The module and importer types

The full type list

  Governance module
    maintainer_action   MA   open → done | dropped
  Delivery-assurance module
    artifact            AR   staged → promoted | rejected
    gate_run            GR   recorded, with a three-valued verdict field
                             (pass | fail | cannot_evaluate), never folded into status
    release             RL   planned → published | abandoned
    waiver              WV   active → expired | revoked; expiry required at creation
  Operational-policy module
    mode                MO   active → retired
    tier_assessment     TA   recorded
  Concurrent-operation module
    session_lease       SL   held → released | reconciled
  Reserved
    transaction         TX   excluded from the adopter standard; name and namespace reserved
    (none)              CL   reserved unassigned, so it can never half-collide with "changelog"
    (none)              LF   reserved unassigned; the reference tooling still recognizes
                             legacy_fragment (quarantined → resolved | ignored) in stores
                             holding such records from its retired import path
  

These are outline state sets; the full module record schemas ship with the module schemas release. The delivery-assurance release record, where enabled, references a version.toml release row by version string: the ledger row is the fact, the record is the delivery-assurance envelope around it.

The standard reserves the LF namespace unassigned and defines no legacy_fragment type (spec section 8.1); the reference tooling still recognizes the type in existing stores and never scaffolds it. Under the reference tooling's retired import contract, everything an import could not confidently map became quarantined fragment data with source path, digest, span, and run ID, so nothing was dropped. Ordinary import is now retired and refuses with exit 2, nothing in the reference CLI creates legacy_fragment records, and the standard directs new imports to the imported series with verbatim unparsed text instead (spec section 8.1); the type remains in the tooling for existing stores and evidence. A new store's counters file has no LF namespace; a store scaffolded by earlier reference tooling may carry LF (at zero, or higher if it imported records), and doctor and re-adoption accept it. That acceptance is the reference tooling's 1.2.0 behaviour and diverges from the standard, whose section 9.2 validation refuses a 1.2.0 manifest as a store. In a store that holds legacy_fragment records, as in a store with module-tier records, doctor reports cannot-evaluate and opf render --write refuses, because the baseline validator does not validate those records' content schemas. Module-type index mirrors are deferred until the module record schemas ship; the reference renderer covers the baseline types today and reports a per-record layout or an unknown view as a clear cannot-evaluate rather than guessing.

The problem it solves

Not every project needs delivery assurance or operational-policy records on day one.

Default-off modules are intended to keep the baseline small while sharing an extended vocabulary. Enabling a module permits its type declarations with normative namespaces; declaring a module type without enabling its module is a validation finding. Enabling it does not supply a missing record schema.

Enabled by

manifest.toml

One manifest edit per module, under the adopter's own review flow.

Created by

By process, once a module is enabled; the reference CLI's opf record create authors baseline types only, since the module record schemas have not shipped. Nothing creates legacy_fragment records now: ordinary import is retired and refuses, and the type remains only for existing stores.

Read by

opf doctor

opf doctor for module-toggle validity (a declared module type requires its enabled module); the AIQT profile, which requires the governance, operational-policy, and concurrent-operation modules.

What it protects