{{PROJECT_NAME}} Archive — Specification

Version: 2.0 · Status: active · Maintained by: the Archivist (a Claude Code agent)

This specification defines how the {{PROJECT_NAME}} preservation archive is structured, what belongs in it, the version-retention policy, and how integrity is guaranteed. It is the authoritative reference for anyone (human or agent) adding to or verifying the archive.

v2.0 change: scope expanded from “core & foundational” to all project documents, and a per-document version-retention policy (first + latest + milestones) was adopted. The previous flat core/ layout was replaced by documents/<doc>/{first,latest,milestones}/.

1. Purpose

Preserve every authored document in the project as faithful, verifiable, version-tracked copies — so the project’s history and current state cannot be silently lost or altered.

2. Scope — what gets archived

All authored project documents. This includes, at minimum:

• Vision/strategy docs (e.g. docs/concept.md)
• Standards/specs and prompts (e.g. prompts/thoroughness-gaps.md)
• Operating contracts (e.g. CLAUDE.md, CONTRIBUTING.md)
• Agent and rule definitions (e.g. .claude/agents/*.md)

Excluded: the archive’s own metadata (README.md, SPECIFICATION.md, MANIFEST.md) — to avoid recursion — and purely generated/transient build output. When in doubt, archive it.

Dated operational records (e.g. reports/<date>-briefing.md and reports/<date>-report.md) are write-once logs that do not evolve; they are preserved via git but are not given first/latest slots in this manifest. (The convention doc reports/README.md is versioned.)

Dated review records (e.g. reviews/<date>-*.md) are archived with first/latest slots. Reviews differ from reports in that they may accrete resolution annotations, status updates, and follow-up findings after initial publication — so tracking first vs. latest is meaningful. The convention doc reviews/README.md is also versioned.

3. Version-retention policy

For every document, the archive keeps:

• First is captured from the commit where the document first appeared and is never modified thereafter.
• Latest is refreshed (verbatim copy from the working tree) on every authoritative change, and its checksum in MANIFEST.md is updated.
• Milestones are snapshots taken at named project milestones. Milestone definitions are TBD — see §4. Until defined, milestones/ holds only a .gitkeep placeholder.
• Full version history beyond these slots lives in git; these slots are the curated, guaranteed-retained set.

4. Milestones

Triggers (MS-## — what counts as a milestone):

• template-v1 — the template scaffolding is complete and coherent.
• first-ideation-spec — the first real JSON ideation spec is injected.
• mvp-spec-frozen — a venture’s concept + rubric + plan are frozen.
• first-product-slice — the first working product slice ships.
• funding-gate — a funding / partnership decision point.

How milestones are captured:

• Whole-repo milestones (e.g. template-v1) are captured as an annotated git tag named for the slug, plus a Verification-log row. Git already holds every document at that commit, so no per-document copies are made.
• Per-document snapshots remain available for specific high-value docs at documents/<doc>/milestones/<NN-slug>/<filename> (each with a manifest row), when a single document’s state at a milestone is worth pinning.

5. Directory layout

archive/
├── README.md          # Archivist charter
├── SPECIFICATION.md   # This document
├── MANIFEST.md        # Inventory + provenance + checksums (per version)
└── documents/
    └── <doc>/                 # one folder per archived document
        ├── first/<filename>   # immutable first version
        ├── latest/<filename>  # most recent version
        └── milestones/        # named milestone snapshots (TBD)

The authoritative list of current <doc> folders is the inventory in MANIFEST.md (maintained by scripts/archive-manifest.sh); it is not duplicated here.

6. Naming & provenance

• Version files keep the document’s original filename inside each slot folder.
• Every archived version MUST have a row in MANIFEST.md recording: document · slot · source path · origin commit · captured (UTC) · SHA-256 · status.

7. Preservation rules

• Verbatim copy. first/ is extracted from its origin commit (git show <commit>:<path>); latest/ is a byte copy (cp) of the working file. Never re-type or reformat while archiving. Confirm with cmp.
• No silent edits. Foundational content is not rewritten during archiving; any source cleanup happens on the working copy first and is disclosed there.
• concept.md is protected — always present, always matching its recorded checksum.

8. Integrity

• Algorithm: SHA-256, recorded in MANIFEST.md.

• Verify:

  # Recompute every archived version
  find archive/documents -name '*.md' | sort | xargs sha256sum
  
  # Confirm a latest copy still matches its working source
  cmp docs/concept.md archive/documents/concept/latest/concept.md
  

• A mismatch means the archive has drifted and must be reconciled.

9. Update workflow (when a document changes)

1. Refresh latest/<filename> (verbatim copy from the working tree).
2. Update that document’s latest checksum + capture date in MANIFEST.md.
3. Leave first/ untouched.
4. If the change coincides with a named milestone, also add a milestone snapshot (§4) and a manifest row.

10. Roles

• Archivist (Claude Code agent): captures versions, computes checksums, updates the manifest, verifies integrity — per README.md.
• Maintainer (human): decides what is authoritative, defines milestones, and authorizes any supersession or removal.