# Presentation source freshness

This policy defines the source boundary for a future claim that the Presentation
Center covers the repository. The current library is still expanding. Its
working inventory remains pinned to `1ceae52c7896a59ac74a4429d410f3218f0b91c6`;
passing its freshness checks means that immutable snapshot is reproduced
exactly, not that the library is current with a moving branch or complete.

## Boundary decision

A final claim must name two full Git commit SHAs:

- the **source cutoff** is a commit already reachable from `origin/main`, chosen
  after every intended product, domain, documentation and Docs Center generator
  change has landed;
- the **claim revision** contains the finished presentations and verification
  evidence and descends from the source cutoff.

The documentation inventory excludes the Presentation Center itself. After the
source cutoff, changes may therefore be limited to
`docs/presentations/presentation-center/` and `tools/presentations/`. Any other
changed tracked path invalidates the cutoff. Select a newer cutoff, assess the
new delta and repeat the repin rather than describing the older inventory as
current. A final statement must say **complete through `<source-cutoff>`**, with
the full SHA and evidence receipt; it must not say “complete on main” without a
new check.

This path rule is deliberately stricter than guessing which changed file might
affect Docs Center discovery. It catches new product and domain roots, newly
registered pages, linked Markdown, generator inputs and deletions that an
old-inventory-only comparison could miss.

The complete-tree repository projection does contain the cutoff-era versions of
those two paths. Their later changes are a disclosed self-hosting exception:
they implement or evidence the claim and fall after the stated source cutoff.
The final receipt must enumerate and review every allowed changed path and bind
the exact changed-path set. The exception cannot conceal product, domain,
runtime or general documentation changes under an allowed directory, and it does
not change the wording “complete through `<source-cutoff>`.”

## Candidate assessment and atomic repin

Before changing the working pin, collect the proposed cutoff into a separate
staging directory. Compare the candidate with the working inventory and retain
path-level records for added, removed, byte-changed and unchanged authored
sources, generated pages, spaces, domains and totals. Review every generator or
discovery-scope change explicitly. Generated output must come from the actual
candidate Docs Center build; a Git path diff is only an early warning and cannot
replace recollection.

Accept the candidate by updating one coherent change set:

1. Set `meta.json` and the documentation, repository and workflow inventories to
   the same source cutoff and tree.
2. Replace the documentation index and every declared source/generated shard,
   then rebuild the repository and workflow projections that depend on it.
3. Regenerate teaching reports and delivery artifacts from the accepted pin.
4. Retain the candidate comparison, supervised collection logs and exact hashes
   in a new verification receipt.

Do not partially copy candidate shards into the working inventory. The inventory
loader rejects mixed revisions and corrupt shard hashes; the freshness gate also
rejects disagreement between the three inventory families, their Git tree,
generator digest and cross-index hashes.

## Assignment invalidation

Unit identity surviving a repin does not by itself preserve review. Apply these
rules to the candidate comparison:

- Added meaningful units begin unassigned and must receive substantive review.
- Removed units make their old assignments unknown; retire or replace those
  assignments deliberately.
- A changed authored file invalidates old-revision review for the whole file,
  even if an individual unit kept its ID or text. Recheck the source context,
  citations, explanation and slide before moving the assignment to the new
  revision.
- Generated pages must be reviewed against the regenerated candidate output.
- The supplemental-revision bridge may retain an old assignment only when the
  complete authored source file is byte-identical at both revisions. It does not
  extend inventory scope or excuse a changed file.
- Any changed slide, diagram, inherited chapter or release scope invalidates its
  stored slide fingerprint.

The coverage reports must continue to distinguish structural, unassigned,
assigned, reviewed and stale units. Recollection is discovery evidence; it never
turns a unit into teaching evidence.

## Required final gates

Run expensive collectors under the repository resource supervisor and retain
their logs. At the claim revision `<R>`, with accepted source cutoff `<S>`, all
of these must pass:

```sh
python3 tools/presentations/check-inventory-freshness.py --check
python3 tools/presentations/run-supervised.py python tools/presentations/inventory-center.py --check
python3 tools/presentations/run-supervised.py python tools/presentations/inventory-repository.py --check
python3 tools/presentations/run-supervised.py python tools/presentations/inventory-workflows.py --check
python tools/presentations/check-center-coverage.py --check --require-complete
python tools/presentations/check-workflow-coverage.py --check --require-complete
python3 tools/presentations/check-inventory-freshness.py --check --require-final --source-cutoff <S> --release-revision <R>
```

The final freshness command requires literal full SHAs. It verifies that the
cutoff is on `origin/main`, every inventory family uses its exact tree, the
claim descends from it, and only the two declared Presentation Center prefixes
changed afterward. The complete teaching gates remain separate and must pass in
the same receipt.

During expansion, `check-inventory-freshness.py --check` validates the immutable
working pin and reports drift from it without treating that drift as final
freshness. Running `--require-final` against the old pin is an expected failure
while newer repository work exists.
