Pointer, meta and generated

Template

A single [store] table. target = "dir:." is the default written by opf init. A target names the store repository in one of four forms: dir:<path> or a bare path (a directory that is, or will be, its own git repository); git:<url> or a bare git URL (any git remote on any host); github:<owner/repo> (a creation convenience that resolves to an ordinary git URL); and gitlab:<owner/repo> (the same, for GitLab). A relative dir: path resolves against the product repository root, the named fixed root for this file; any other path in a pointer must be absolute.

Resolution takes the local override first, then the committed pointer, then, where neither exists, the default location, where a valid manifest resolves as the store. No pointer and no default store is the not-adopted state, and opf init is the remedy. Store relocation re-points the committed pointer and the manifest's recorded sync target in the same change, so the pointer, the manifest, and the actual remote never disagree across a landed state; the integrity layer checks that agreement. The pointer has no generated view of its own: it is lowercase machine source, never a deliverable and never hand-authored truth a human is meant to read first.

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:." (it refuses to run where any pointer already exists); updated by opf migrate, as part of the single recorded relocation change; read by every verb at every store resolution, and by opf doctor for 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}). The archive directory also carries the rotated record and worklog files themselves, preserved byte for byte. Coverage gates read active and archive together, so rotation never changes any gate's answer, and counters.toml is untouched, preserving ID permanence. Retention is indefinite by default; an adopter bound by a retention policy applies it as a recorded maintainer decision governing archival, never as deletion of a record. Archived records have no generated view of their own; they surface through the same gates and coverage checks as active ones, read together.

The problem it solves

Active indexes should stay small without history getting quietly thinner.

The enumeration is what makes a silent removal detectable: every movement is recorded, so a record cannot vanish under the name of rotation, and validation can confirm that every ID exists in exactly one active or archived location.

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, gated on a valid whole-store verdict; regenerated only, so hand edits are drift, reported by opf render --check and opf doctor; read by machine consumers of the decision record and by the byte drift gate.

What it protects