blackroad-os-archive/workflows/archive-workflow.md

Archive Workflow: Finalize & Archive 🧬📥

Purpose: Define how content moves from source repos to permanent archive status
Last Updated: 2025-11-24
Applies To: IP artifacts, protocols, major decisions, finalized documentation

---

Overview

This workflow describes the complete lifecycle of a document from initial draft to archived canonical version. The archive captures finalized, blessed versions while source repos continue to evolve.

🔄 The Four Stages

Draft (Source Repo) → Review → Archive → Canonical Status

---

Stage 1: Draft Stage 📝

Location: Source repository (not archive)

Where Drafts Live:

• Research & IP: blackroad-os-research
• Documentation: blackroad-os-docs
• Infrastructure specs: blackroad-os-infra
• API specs: blackroad-os-api
• Brand guidelines: blackroad-os-brand
• Core protocols: blackroad-os-core

Activities:

1. Content is created following source repo's contribution guidelines
2. Iterative development through PRs
3. Internal review and refinement
4. Collaboration and feedback

Exit Criteria:

• Content is complete and stable
• Internal review approvals obtained
• Ready to be "frozen" as a reference version

---

Stage 2: Review Stage 👀

Location: Still in source repository

Process:

1. Final review in source repo

   • Technical accuracy verified
   • Completeness confirmed
   • Metadata prepared (source info, version, date)

2. Label applied: Status: Ready for Archive

   • Signals that content is archival-ready
   • Triggers monitoring by archive agents

3. Archive request created:

   • Option A: Issue in blackroad-os-archive with:

     • Link to source file
     • Commit SHA
     • Category (IP, Legal, Workflow, etc.)
     • Archival reason
     • Any special instructions

   • Option B: Comment in source repo PR:

     • Tag archive team: @BlackRoad-OS/archive-team
     • Specify archive category
     • Request archival

Exit Criteria:

• Archive request acknowledged
• Source content is stable (no active edits)
• Metadata is complete

---

Stage 3: Archive Stage 📥

Location: blackroad-os-archive repository

Process:

3.1 Create Archive Copy

1. Create new file in appropriate archive directory:

   • ip/ for intellectual property, protocols, frameworks
   • legal-finance/ for legal/financial docs
   • workflows/ for process documentation
   • snapshots/ for point-in-time captures

2. Add metadata header:

   # [Document Title]
   
   **Category:** [IP | Legal | Finance | Workflow | Protocol]  
   **Source Repo:** `BlackRoad-OS/[source-repo-name]`  
   **Source Path:** `path/to/original/file.md`  
   **Source Commit:** `[full git SHA]`  
   **Archived On:** YYYY-MM-DD  
   **Archived By:** [agent:name | human:username]  
   **Status:** Final
   
   ---
   
   [Original content with minimal normalization]
   

3. Content normalization (minimal):

   • Convert to standalone Markdown
   • Resolve relative links to absolute URLs
   • Remove source-repo-specific references
   • Keep content integrity intact

3.2 Update Indexes

1. Update catalog/INDEX.md:

   - [Document Title](../category/document-name.md)  
     - Category: [category]
     - Archived: YYYY-MM-DD
     - Source: `BlackRoad-OS/[repo]` @ `[commit]`
   

2. Update catalog/timeline.md (if milestone):

   ## YYYY-MM-DD
   - **[Document Title]** archived - [brief description]
   

3. Update catalog/services.md (if new repo/service):

   • Add repo to catalog if not already listed

3.3 Create PR in Archive

1. Branch name: archive/[category]-[short-name]
2. PR title: [Archive] Document Title
3. PR description:

   ## Archive Request
   
   **Source:** [link to source file]
   **Category:** [category]
   **Commit:** [SHA]
   
   ## Reason for Archival
   [Why this is being archived now]
   
   ## Changes Made
   - Added metadata header
   - Placed in `[directory]/`
   - Updated catalog indexes
   
   ## Checklist
   - [x] Metadata header complete
   - [x] Content is standalone Markdown
   - [x] No secrets included
   - [x] Index updated
   - [x] Timeline updated (if applicable)
   

3.4 Review & Merge

1. Automated checks:

   • No secrets detected
   • Valid metadata format
   • Links functional
   • No large binaries

2. Human review:

   • Content appropriate for archive
   • Category correct
   • Metadata accurate
   • Indexes properly updated

3. Merge to main branch

Exit Criteria:

• PR merged to blackroad-os-archive
• File available in archive
• Indexes updated
• Git history clean

---

Stage 4: Canonical Status ✅

Location: Archive is now source of truth

What It Means:

• Archived version is canonical at that point in time
• Source repo may continue to evolve (working versions)
• Archive captures blessed version for reference, filing, prior art

Usage:

1. Reference: Link to archived version for stable citations
2. Prior art: Use in IP filings or legal context
3. Historical record: Understand what was decided/created when
4. Baseline: Starting point for future iterations

Maintenance:

• Archive is immutable for that version
• New versions get new archive entries with updated dates
• Living documents marked with Status: Living Document in metadata
• Historical versions marked with Status: Historical if superseded

---

🤖 Agent Automation

For AI Agents:

Monitoring:

1. Watch source repos for `Status: Ready for Archive` labels
2. Check for archive requests in issues
3. Scan for explicit archive mentions in PRs

Processing:

1. Validate source content is stable
2. Extract metadata (repo, path, commit, date)
3. Create archive branch
4. Copy content with metadata header
5. Update indexes
6. Create PR with standard description
7. Request review

Quality Checks:

1. Verify no secrets in content
2. Confirm metadata completeness
3. Validate links work
4. Check category placement
5. Ensure indexes updated

---

📋 Checklist Template

Use this checklist when archiving content:

- [ ] Source content is finalized and stable
- [ ] Archive request created or label applied
- [ ] Appropriate category selected
- [ ] Metadata header added with all fields
- [ ] Content copied to correct directory
- [ ] Links converted to absolute URLs
- [ ] No secrets or sensitive data included
- [ ] catalog/INDEX.md updated
- [ ] catalog/timeline.md updated (if milestone)
- [ ] PR created with clear description
- [ ] Review requested
- [ ] Automated checks passed

---

⚡ Quick Reference

Archive Directory Mapping:

• IP/Protocols → ip/
• Legal docs → legal-finance/
• Financial models → legal-finance/
• Process docs → workflows/
• Ecosystem snapshots → snapshots/YYYY-MM-DD/
• Decisions → ip/ or snapshots/ depending on scope

Metadata Fields (Required):

• Category
• Source Repo
• Source Path
• Source Commit (full SHA)
• Archived On (YYYY-MM-DD)
• Archived By
• Status

Common Statuses:

• Final - Stable, canonical version
• Living Document - Continues to be updated
• Historical - Superseded by newer version
• Reference - For reference only

---

🆘 Troubleshooting

Q: Source content is still changing
A: Wait until it's stable. Don't archive work-in-progress.

Q: Multiple versions of same document
A: Use versioned filenames: document-v1.0.md, document-v2.0.md or date-based.

Q: Sensitive information in content
A: Don't archive. Request private storage or redact sensitive portions.

Q: Source repo deleted or unavailable
A: Note in metadata: "Source repo no longer available. Archived from [context]."

Q: Not sure about category
A: Ask in archive issue or default to most specific category.

---

Remember: The archive is for finalized, canonical versions. When in doubt, wait until content is truly ready. Quality over speed. 🕯️