Story: Remove the #+version field and finish doc-format cleanup

Table of Contents

This page documents a story in Sprint 20. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

Sprint 18's Doc format cleanup story marked all five tasks DONE, but two of them — drop the #+version field and remove v2 terminology — were never actually carried through. The repo still contains:

  • 14 .org files (plus the v2-capture emacs snippet) that carry #+version: 2;
  • projects/ores.codegen/scripts/doc_version_audit.py, fully intact, despite task 5 claiming it was retired;
  • active guidance (doc/orientation.org, doc/llm/memory/memory.org, several recipes and skills, and the version_field_is_schema_version memory) that still mandates #+version: 2 on every new doc and points at the audit script as a CI gate;
  • stale v2_doc_* script references in ores.codegen modeling and docs that point at files renamed away in sprint 18.

These leftovers leave two contradictory decisions on record (drop the field vs. keep it as a schema version) and confuse every new session. This story finishes the job in the agreed direction: the #+version field is removed altogether. After it, the word "v2" and the #+version field appear nowhere except in the historical sprint 17–18 records that document the migration itself.

Status

Field Value
State DONE
Parent sprint Sprint 20
Now Nothing.
Waiting on Nothing.
Next Nothing — story complete.
Last touched 2026-06-09

Acceptance

  • No .org file in the repo contains a #+version: line (sprint 17–18 historical records included — they describe the field, they need not carry it).
  • projects/ores.codegen/scripts/doc_version_audit.py no longer exists, and nothing references it (CI, validate_docs, s3_star_audit.org, recipes).
  • No active guidance doc (orientation, memory, recipe, skill, runbook, meta) instructs anyone to add #+version: or to run the audit script.
  • The version_field_is_schema_version memory is deleted (its premise — that the field is a kept schema version — is the decision we are reversing).
  • No file or doc-reference under projects/ores.codegen/ names v2_doc_, generate_v2_doc.sh, v2_doc_generate.py, or v2_doc_generator.md.
  • The v2-capture emacs snippet is renamed and no longer emits #+version:.

Tasks

Task State Start End Description
Strip #+version from all remaining org files DONE 2026-06-08 2026-06-09 Remove the #+version: line from the 14 org files and the v2-capture snippet that still carry it.
Retire the doc_version_audit.py script DONE 2026-06-08 2026-06-09 Delete doc_version_audit.py and remove every reference to it from CI, validate_docs, and function docs.
Purge #+version guidance from active docs DONE 2026-06-08 2026-06-09 Remove version-field instructions from orientation, memory, recipes, skills, and document_types; delete the schema-version memory and retire the audit recipe.
Fix stale v2 codegen references DONE 2026-06-08 2026-06-09 Update ores.codegen modeling, puml, architecture, and doc_generator.md to drop v2_doc_ script names; rename the v2-capture snippet.

Decisions

  • Direction: remove the field entirely, not keep it. Sprint 18 left two conflicting decisions on record — task_drop_version_field (remove it) and the version_field_is_schema_version memory (keep it as a schema version). We resolve in favour of removal: with the v1→v2 migration long complete there is only one format, so the field carries no information.
  • Sprint 17–18 historical records are in scope this time. Sprint 18 excluded them to keep the field-strip PR small. Since the field is going away entirely, any historical record still carrying #+version: gets stripped too. Their prose describing the field as history stays untouched.
  • Task split mirrors the unfinished sprint-18 work: strip the field from files (finishes task 5's file scope), retire the audit script (finishes task 5's tooling scope), purge the guidance (finishes tasks 4 + 5's doc scope), and fix the stale v2 codegen references (finishes task 3's caller-update scope).

Review

# Comment summary File Decision Notes
1 #+version: still listed as active frontmatter in org_roam.org doc/knowledge/documentation/org_roam.org:48 Fixed in e8b6b387e Removed , and =#+version:,= from the sentence

Out of scope

  • Re-running codegen or templates — they were already cleaned in sprint 18 and emit no #+version: today; this story only removes what was left behind.
  • The historical prose in sprint 17–18 story/task records that describes the v1→v2 migration. That is accurate history and stays as-is.

Emacs 29.1 (Org mode 9.6.6)