Archival and Retention Standard¶
This standard governs how superseded, deprecated, or otherwise no-longer-current documents are handled. The core rule: authoritative documents are never silently deleted.
Marking a document superseded or deprecated¶
When a document is replaced or retired:
- Update its
statusfield todeprecated(no longer current, kept for reference) or, where a specific replacement exists, note the replacement relationship via thesupersedes/superseded_byconvention described below. - Do not delete the file or remove its content. Leave it in place at its existing path so existing links continue to resolve, unless the archival step below applies.
- If a new document replaces it, the new document's front matter
supersedesfield lists the old document's path ordocument_id. The old document should gain a note near the top (or in its own front matter, if asuperseded_by-style field is in use perdocs/governance/document-metadata-standard.md) pointing forward to the new document.
Why keep the record rather than delete it¶
Retaining superseded documents preserves the reasoning trail: why something was decided, what was tried before, and when it changed. This matters especially for ADRs (see docs/decisions/README.md), where the historical decision itself has ongoing reference value even after being superseded.
Retention of working material¶
Material under work/ (active plans, in-progress notes) that is completed, abandoned, or superseded is moved to work/archive/ rather than deleted, preserving the same trail for less formal material. Working notes that never reach durable value (e.g., a scratch note superseded within the same session) may be cleaned up more casually, but anything that informed an actual decision or specification should be retained.
No silent deletion of authoritative documents¶
"Authoritative" here means any document with a document_id under docs/company/, docs/governance/, docs/architecture/, docs/standards/, docs/decisions/, or an approved/proposed product or component specification under ventures/. These are never removed from the repository without a documented reason (an ADR, if the removal itself is a material decision, or at minimum a clear commit message and an entry in CHANGELOG.md explaining why). Ordinary working files outside this scope are not held to the same bar.
Registries¶
If a document tracked in a portfolio/ registry is deprecated or superseded, its registry entry must be updated to reflect the new status at the same time — a stale registry entry pointing to a deprecated document as if it were current is treated as a defect (see docs/architecture/registry-architecture.md).