Pointer, meta and generated

Template

A single [store] table. target = "dir:." is the default written by opf init. The standard defines four target forms: dir:<path> or an absolute bare path; git:<url> or a bare git URL; github:<owner/repo>; and gitlab:<owner/repo>. The host forms are specified creation conveniences that resolve to ordinary git URLs. The reference resolver recognizes remote forms but cannot resolve them without clone or sync support; it currently resolves local stores only. Relative dir: paths resolve against the product repository root; other filesystem paths must be absolute.

Resolution tries the local override, then the committed pointer, then the default location when neither pointer exists. No pointer and no default store is the not-adopted state, and opf init is the remedy. The standard requires relocation to update the pointer and recorded sync target together; opf migrate is planned in the reference CLI. The pointer is control data and has no generated view.

The problem it solves

The store's location is configuration, not architecture.

A stale pointer aimed at the wrong store would be worse than no pointer, so resolution is validated every time and fails closed: a pointer that does not resolve stops the tool and never falls back silently to the default location.

Declares

Where the store repository lives: a [store] table whose target is dir:. by default (the store rides this repository at .working/), or any location a target can name after relocation.

Read by

opf init opf render opf doctor

Created by opf init with target = "dir:.", refusing an existing pointer; updated by opf migrate (planned; not yet implemented in the reference CLI) in the specified relocation flow. Implemented store readers use it for resolution; opf doctor checks pointer and sync-target agreement.

Committed

Yes: this is the one tracked marker. Because the committed pointer must be safe to publish, anything machine-local or private-only belongs in the uncommitted .opf.local.toml override, which is resolved first and never committed.

What it protects

Template

A closed three-key shape: schema, moved (rows of {id, type, destination}), and worklog_moved (rows of {span, destination}). Rotated records and worklog entries remain in the archive. Coverage checks read active and archived entries together; rotation must preserve released coverage and counter high-water marks. The standard requires indefinite retention by default, with archival policy recorded as a maintainer decision rather than record deletion. Archived records remain inputs to integrity and coverage checks.

The problem it solves

Active indexes should stay small without history getting quietly thinner.

Rotation records enumerate moved IDs. Validation checks their destinations and the active/archive partition; these checks are intended to expose missing or duplicated records within their observed inputs.

Records

Every rotated ID as a row of {id, type, destination}, and every moved worklog span as a row of {span, destination}, each carrying where it went.

Written by

Created by the first rotation into a year bucket (never scaffolded); updated by the rotation process, appending the moved IDs and spans.

Validated by

opf doctor

Read by opf doctor for archive integrity, the exactly-one-location rule, and ID partition, and by every coverage gate, which reads active and archive together.

Invariant

Rotation is enumerated relocation, never deletion and never ID reuse. Records in unqualified terminal states may rotate on manifest-declared age or size thresholds; open records, active blocks, unresolved decisions and fragments, unexpired waivers, the current handoff, and the unreleased worklog tail never rotate, and worklog spans rotate only under the release rule, once released and frozen.

What it protects

Template

The payload (projection contract v1) carries schema = 1 and projection = "decisions"; four arrays of tables, one per source type, each row sorted by numeric ID and projecting the full base record with x-<vendor> extension tables excluded as profile-owned data; and one [derived] table carrying the decision-resolution join's output (the effective and superseded pending-decision IDs, numerically sorted) and nothing beyond the closed transform vocabulary. The do-not-edit header is a leading TOML comment block naming sources, schema and generator versions, a source-set digest, and the regeneration command, with no timestamp.

The determinism requirements apply verbatim: UTF-8, LF, stable ordering, no locale-dependent sorting, no wall-clock content, no network access, and no model involvement. Advisory activity over a projection, an assistant-side prediction, dedup, or pattern-spotting pass, is a read-time activity outside the generator: the generator invokes no model and adds no model-generated interpretation. The views it renders reproduce the declared source records, so content those records carry, including assistant-authored text, still needs review.

The problem it solves

A machine consumer of the decision record should not have to parse Markdown, read four indexes, and re-derive the supersession chain itself.

The projection gives it one deterministic file with the join already computed, under exactly the same render, drift, and doctor gates as any declared view, with no new gate. It is a third generated-output class beside the deterministic views and the curated changelog.

Rendered from

pending_decision autonomous_decision maintainer_decision preference_pattern

Projected from the four decision source types, one array of tables per type, with the decision-resolution join already computed. Never hand-edited: it is generated output, not a source.

Kind

A machine projection: a deterministic, byte-drift-gated TOML deliverable, the machine counterpart to the composed DECISIONS.md view. It is one of the thirteen outputs the scaffolded manifest declares, rendered beside that view from the same four sources.

Gated by

opf render opf doctor

Created by opf render --write after source-integrity checks. Post-write validation checks source integrity and regenerated outputs; disagreements trigger a rollback attempt, with failures reported. Other deliverable failures can still cause a nonzero exit. Hand edits are byte drift checked by opf render --check and opf doctor; machine consumers read the generated projection.

What it protects