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:
- Set
meta.jsonand the documentation, repository and workflow inventories to the same source cutoff and tree. - Replace the documentation index and every declared source/generated shard, then rebuild the repository and workflow projections that depend on it.
- Regenerate teaching reports and delivery artifacts from the accepted pin.
- 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:
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.