luum-home/luum-cognitive-os/adr-tombstone

ADR Tombstone

This is an agentic primitive: the reusable procedure and deterministic tooling for tombstoning ADR records. The ADR files it creates are documentation records, not the primitive itself.

Use this skill when an ADR number remains reserved but the original decision text should no longer live in active first-party documentation.

Boundary

• Primitive: skills/adr-tombstone/, scripts/adr_tombstone.py, scripts/cos-adr-tombstone, and their tests.
• ADR record: docs/02-Decisions/adrs/ADR-NNN-tombstone.md, generated or repaired by the primitive.
• Distinguish the tombstone ADR record from the primitive that manages tombstones.

Rules

• Keep each ADR number bound to one decision lineage.
• Prefer a neutral file name: docs/02-Decisions/adrs/ADR-NNN-tombstone.md.
• The first heading matches the filename number.
• The tombstone includes the same required ADR sections as normal ADRs.
• Keep removed integration names and other purged terms out of tombstone text.
• Update links from the removed ADR filename to the neutral tombstone filename.
• Validate the full ADR sequence after creating or repairing tombstones.

Workflow

1. Identify the ADR number and any forbidden terms to keep out of the tombstone.
2. Run the deterministic helper:

scripts/cos-adr-tombstone \
  --number NNN \
  --title "Removed architecture decision" \
  --reason "The original decision content was removed from the active architecture surface." \
  --forbidden-token "term-to-keep-out" \
  --validate-forbidden-tokens

1. If only filling a numbering gap, omit --forbidden-token and use a reason like:

This ADR number is intentionally reserved so the ADR sequence remains contiguous.

1. Validate:

python3 -m pytest tests/unit/test_adr_tombstone.py tests/contracts/test_adr_numbering_integrity.py -q

1. If the task is a full purge, also run the repository-specific no-reference

contract for the removed surface.

Output expectations

Report the tombstone path, removed ADR files, updated references, and validation commands. Commit or push only when explicitly asked.